Answer API

The endpoint behind Answers. You send a question, Miso builds an answer from your catalog, and you poll for it.

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

%%{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 app
    participant M as Miso

    A->>M: POST /v1/ask/questions
    M-->>A: question_id, and nothing else
    Note over M: the answer does not exist yet

    loop every 1 to 2 seconds
        A->>M: GET /v1/ask/questions/{question_id}/answer
        M-->>A: finished false, answer_stage, the text so far
        Note over A: render the partial answer while you wait
    end

    A->>M: GET /v1/ask/questions/{question_id}/answer
    M-->>A: finished true, answer, sources, follow-ups
    Note over A,M: about 12 seconds end to end

Ask a question

POST /v1/ask/questions

Field	Type	Notes
`question`	string	Required. What the reader asked.
`anonymous_id`	string	The visitor. Send the same value for the same person.
`user_id`	string	The signed-in reader. Send this instead of `anonymous_id`.
`user_type`	string	The tier, for metering. Without it, metering never runs.
`parent_question_id`	UUID	The previous question, to continue a thread.
`fq`	string	Restrict the passages the answer can use. See Filter Syntax.
`metadata`	object	Your own values, stored with the request and returned with the answer.

curl -X POST "https://api.askmiso.com/v1/ask/questions" \
  -H "X-Api-Key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "anonymous_id": "visitor-8f3a1c",
    "question": "What did Wikinews report about the Linux operating system?"
  }'

The response carries the id and nothing else. The answer does not exist yet:

{
  "message": "success",
  "data": {
    "question_id": "08608817-f178-4898-95b6-5849667ac03b"
  }
}

Poll for the answer

GET /v1/ask/questions/{question_id}/answer

Poll every 1 to 2 seconds until finished is true. The body grows as Miso works, so you can render the answer while it is written.

curl "https://api.askmiso.com/v1/ask/questions/$QUESTION_ID/answer" \
  -H "X-Api-Key: YOUR_SECRET_KEY"

Stop on finished. Never test answer_stage. It is a sentence for a reader, and Miso translates it into the language of your app. A typical answer moves through these stages in about 12 seconds:

""                                                     queued
"Researching different sources"
"Doing more research, this may take a little longer"
"Generating summary"                                   finished: true

What you get back

{
  "message": "success",
  "data": {
    "finished": true,
    "finish_reason": "success",
    "blocked_reason": "none",
    "question": "What did Wikinews report about the Linux operating system?",
    "answer": "Red Hat announced in December 2020 that it would move focus away from CentOS Linux in favour of CentOS Stream [1][2]…",
    "sources": [
      {
        "product_id": "wikinews-2911067",
        "title": "Red Hat to move focus away from CentOS in favour of Stream",
        "url": "https://en.wikinews.org/wiki/…",
        "date": "2020-12-14T00:00:00+00:00",
        "snippet": "Red Hat announced the end of CentOS Linux as a rebuild…",
        "highlight_text": "CentOS Stream",
        "boosted": false,
        "_attribution_length": 4845,
        "_attribution_length_percentage": 29.96
      }
    ],
    "followup_questions": ["What is Rocky Linux, and who started it?"]
  }
}

Field	What it is
`answer`	The text, in Markdown, with `[1]` markers that point at `sources`.
`sources`	The articles the answer cites, in citation order.
`followup_questions`	Suggested next questions. Render them as links.
`finish_reason`	`success` when the pipeline completed.
`blocked_reason`	`metering` when a limit stopped the answer. `none` otherwise.

Every field is listed in Answer Response Fields, which also explains the attribution percentages.

A refusal is not an error

When Miso finds nothing relevant, it returns 200, finish_reason: "success", an empty sources, and text that says so:

Unfortunately, I couldn't find relevant information in my knowledge base to answer that question.

Check the catalog before you check your code. The usual causes are an upload that has not finished, or a question outside your content.

Follow-up questions

Send parent_question_id to continue a thread. Miso reads the earlier turns, so the reader can write "and after that?" without repeating the subject.

Threads are stored, and a reader can return to them later. See User History.

Answer Response Fields — every field in the answer.
Source Attribution — what the percentage on each source measures.
Filter Syntax (fq) — restrict what an answer can cite.
Metering & Entitlements — limit answers per reader.
Ask — Quick Start — the SDK that does all of this for you.

Filter Syntax (fq)

Answer Response Fields