Hybrid Search API

One call returns keyword results and starts an AI answer over the same catalog. It is the endpoint behind the Hybrid Search SDK module.

This is the search to use for content. Articles, video and documents bring readers who ask in sentences and want an answer, not only a list. For a product catalog, where traffic is heavy and every query must render at once, use the Search API instead.

Base URL https://api.askmiso.com. Authenticate with the X-API-KEY header, or ?api_key=. See Authentication.

Search (+ answer)

POST /v1/ask/search

curl -X POST "https://api.askmiso.com/v1/ask/search" \
  -H "X-Api-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "interest rate cuts 2026",
    "answer": "AUTO",
    "rows": 5,
    "fl": ["title", "url", "cover_image"],
    "fq": "section:\"markets\""
  }'

{
  "message": "success",
  "data": {
    "took": 731,
    "total": 3,
    "question_id": "064bda22-1e30-4411-b735-9370a8e48aa4",
    "miso_id": "85d792d9-50a2-43dc-9…",
    "products": [
      {
        "product_id": "wikinews-2911293",
        "title": "Gregory Kurtzer discusses plans for Rocky Linux with Wikinews…",
        "url": "https://en.wikinews.org/wiki/Gregory_Kurtzer_discusses_plans…"
      }
    ],
    "facet_counts": {
      "facet_fields": {
        "tags": [["Computing", 2], ["FLOSS", 2]]
      }
    },
    "parsed_query": null,
    "suggestion": null
  }
}

The answer is not in this response. You get question_id, and you poll the same endpoint the Ask module uses:

POST /v1/ask/search                       -> products now, plus question_id
GET  /v1/ask/questions/{question_id}/answer  -> the answer, when finished

The search returns in about 2 seconds, and the answer follows about 5 seconds later with 7 sources. Render the results first, then fill the answer in when it arrives.

%%{init: {'theme':'base','themeVariables':{
'fontFamily':'IBM Plex Sans, ui-sans-serif, system-ui','fontSize':'14px',
'actorBkg':'#3148be','actorBorder':'#3148be','actorTextColor':'#ffffff',
'actorLineColor':'#9aa3c0','signalColor':'#9aa3c0','signalTextColor':'#6b7392',
'labelBoxBkgColor':'#f4effc','labelBoxBorderColor':'#cdbcf0',
'labelTextColor':'#40277a','noteBkgColor':'#e8ecfb','noteBorderColor':'#b9c2ea',
'noteTextColor':'#22307a','sequenceNumberColor':'#ffffff'
}}}%%
sequenceDiagram
    autonumber
    participant A as Your page
    participant M as Miso

    A->>M: POST /v1/ask/search (q, answer true)
    M-->>A: products, facets, and a question_id
    Note over A: render the results now, about 2 seconds

    loop until finished
        A->>M: GET /v1/ask/questions/{question_id}/answer
        M-->>A: the answer so far
    end

    Note over A,M: the answer finished about 5 seconds later
    A-->>A: fill the answer in above the results

The search and the answer come back separately. Render the results as soon as they arrive, and let the answer appear when it is ready.

How Miso reads the query

q is a search query, not a sentence Miso guesses at. These operators work, and the counts below come from a catalog of 20,901 news articles.

Two details are worth knowing:

• A bare space means AND. linux kernel and linux AND kernel both return 8. A reader who types more words gets fewer results, not more.
• NOT subtracts. kernel alone matches 16 articles, 8 of which also say linux, so kernel NOT linux leaves 8.
• Quotes narrow. "open source" returns 100, the loose form 317.

Quotes are repaired, not rejected

Miso normalizes the query before it runs:

A malformed query therefore returns results rather than an error.

Order the results

order_by takes a shorthand string, or a list of objects for your own fields. The default is relevance.

The minus sign does not mean descending here. published_at is already newest first, and -published_at reverses it to oldest first. It reads backwards, so check it against your own data before you ship a sort control.

Against a catalog of 20,901 news articles:

2023-05-01  Microsoft, Nware sign 10-year cloud gaming deal
2023-03-09  Netherlands set to further restrict semiconductor technology exports
2021-07-05  Ransomware attack hits over 200 US companies

2004-11-15  Big Linux Beta 3 released
2004-11-16  Longhorn for 2006, according to Gates
2004-11-29  Lycos launches screensaver to increase spammers' bills

A record with no published_at sorts by updated_at. It is not pushed to the end. In the run above, three undated articles appeared in the middle of the list, each in the position its updated_at earned.

Sort on your own fields

Send a list instead of a string. Each entry names a field, and Miso applies them in order:

{
  "q": "technology",
  "order_by": [
    {
      "field": "custom_attributes.word_count"
    },
    {
      "field": "_search_score"
    }
  ]
}

Facet the results

facets returns counts per value, for the products that match the query. Use them to build filters.

The short form is a list of field names:

{
  "q": "technology",
  "facets": ["tags"]
}

{
  "facet_counts": {
    "facet_fields": {
      "tags": [
        ["Science and technology", 1807],
        ["United States", 1010],
        ["North America", 903],
        ["Europe", 484]
      ]
    }
  }
}

Each entry is [value, count], sorted by count, largest first. The default is the 10 most common values.

Control the facet

The long form is an object:

{
  "facets": [
    {
      "field": "tags",
      "alias": "topics",
      "size": 3
    }
  ]
}

{
  "facet_counts": {
    "facet_fields": {
      "topics": [
        ["Science and technology", 1807],
        ["United States", 1010],
        ["North America", 903]
      ]
    }
  }
}

The alias replaces the field name as the key, so two facets on one field do not collide.

include and exclude are case sensitive, and they match anywhere in the value unless you anchor them:

{
  "facets": [
    {
      "field": "tags",
      "size": 5,
      "include": "Comp.*"
    }
  ]
}

That returns Computing (332), Computron (Wikinewsie) (6), Computer Fraud and Abuse Act (3), and Computron (WWC2013) (2). Neither option changes the search results, only the facet values.

Range facets

Group a numeric or date field into buckets you name:

{
  "facets": [
    {
      "field": "custom_attributes.word_count",
      "ranges": [
        {
          "to": 200,
          "key": "short"
        },
        {
          "from": 200,
          "to": 600,
          "key": "medium"
        },
        {
          "from": 600,
          "key": "long"
        }
      ]
    }
  ]
}

{
  "facet_counts": {
    "facet_fields": {
      "custom_attributes.word_count": [["medium", 1495], ["long", 538], ["short", 535]]
    }
  }
}

from is inclusive, to is exclusive, and each bucket needs at least one of them. The response uses your key, and still sorts by count.