Hybrid Search

​

Run keyword search and an AI answer in a single call. This powers the Hybrid Search experience — a search box that returns ranked results next to a generated, cited answer.

How it works

  1. Send the user's query as q.
  2. Decide whether to generate an answer with answer (true / false / "AUTO").
  3. Read ranked documents from data.products.
  4. If an answer was generated, take data.question_id and poll GET /v1/ask/questions/{question_id}/answer for the (streaming) answer — see the Ask APIs.

Use cases

Pick a request example from the dropdown:

  • Search + AI answer — answer: "AUTO" returns results instantly and adds an answer when the query is a question.
  • Search results only — answer: false for a classic results page.
  • Scope to a subscription tier — use fq to restrict candidates.
  • Faceted search — pass facets to get counts for filter UIs.
  • Newest first — order_by: "-published_at".
Body·
required
application/json
  • q
    Type: string
    required

    The search query the user has entered.

  • anonymous_id
    Type: string

    The anonymous visitor who made this query. Used for personalization when there is no user_id.

  • answer

    Controls the AI answer pipeline:

    • true — always generate an answer
    • false — search results only, no answer
    • "AUTO" — let Miso decide per query (recommended; generates an answer only when the query looks like a question)
    • Type: boolean

      Controls the AI answer pipeline:

      • true — always generate an answer
      • false — search results only, no answer
      • "AUTO" — let Miso decide per query (recommended; generates an answer only when the query looks like a question)
  • facets
    Type: array string[]

    Fields to compute facet counts for (e.g. categories, tags, custom_attributes.director). Counts are returned in data.facet_counts — use them to build filter UIs.

  • fl
    Type: array string[]

    Fields to return for each product in data.products. Any uploaded field is allowed, including custom_attributes.*.

  • fq
    Type: string

    A query in Elasticsearch query-string syntax (Lucene) that restricts the candidate products without affecting ranking — use it to scope results (e.g. by section or subscription tier).

    Examples:

    • "section:\"markets\"" — only the markets section
    • "tier:(\"premium\" OR \"pro\")" — only premium/pro content
    • "rating:[4 TO *]" — numeric range, rating ≥ 4
    • "custom_attributes.designer:\"Calvin Klein\"" — filter on a custom attribute
  • metadata
    Type: object

    Arbitrary metadata to store with the request (e.g. {"site": "markets"}).

  • order_by
    Type: string enum

    Sort order of results: relevance (default), published_at (newest first), or -published_at (oldest first). A record with no published_at sorts by updated_at instead. You can also send a list of order-by objects to sort on your own numeric or boolean fields.

    values
    • relevance
    • published_at
    • -published_at
  • rows
    Type: integer

    Number of search results to return in data.products.

  • source_fl
    Type: array string[]

    Fields to return for each answer source. Same field rules as fl.

  • start
    Type: integer

    Offset of the first result — use with rows for pagination.

  • stemming
    Type: boolean

    When enabled, query words are reduced to their root form (e.g. "running" → "run"), improving recall by matching inflected forms.

Responses
  • application/json
Request Example for post/v1/ask/search
curl 'https://api.askmiso.com/v1/ask/search?api_key=YOUR_SECRET_TOKEN' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "q": "interest rate cuts 2026",
  "answer": "AUTO",
  "rows": 5,
  "fl": [
    "title",
    "url",
    "cover_image"
  ]
}'

{
  "message": "success",
  "data": {
    "miso_id": "b7c9e1a2-3d4e-5f60-7a8b-9c0d1e2f3a4b",
    "question_id": "0e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "took": 142,
    "total": 87,
    "products": [
      {
        "product_id": "art-20260612-rates",
        "title": "Central bank signals 2026 cuts",
        "url": "https://example.com/markets/rates"
      }
    ],
    "facet_counts": {
      "facet_fields": {
        "categories": [
          [
            "Markets",
            41
          ],
          [
            "Economy",
            18
          ]
        ]
      }
    }
  }
}

Successful Response