Getting Started

This page takes you from nothing to your first answer. It needs about ten minutes.

Before you start

You need two things: content in Miso, and an API key.

API keys are issued to customers only. The sandbox is the fastest way to see how Answers performs on your own content.

To practise on content that is not yours, follow Example: Wikinews. It loads a free public archive of about 20,900 news articles, and every step is code you can run.

About the sandbox. The request goes to Miso's engineering team. If your content sits behind a paywall, or there is not enough of it, the product team contacts you to agree on a way forward. You can ask for more data later. Most brands need some tuning before they go live.

Which key to use

The calls on this page use the secret key, so run them from a server or a terminal. See Authentication.

Your first API call

An answer is a two-step flow. First you submit the question. Then you poll for the answer. Miso builds the answer in the background, so the first call returns at once.

Pass your key as the X-API-KEY header, or as an api_key query parameter.

1. Submit a question

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": "How do interest rate cuts affect mortgages?"
  }'

const res = await fetch("https://api.askmiso.com/v1/ask/questions", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    anonymous_id: "visitor-8f3a1c",
    question: "How do interest rate cuts affect mortgages?",
  }),
});
const questionId = (await res.json()).data.question_id;

import requests

res = requests.post(
    "https://api.askmiso.com/v1/ask/questions",
    headers={"X-Api-Key": "YOUR_SECRET_KEY"},
    json={"anonymous_id": "visitor-8f3a1c",
          "question": "How do interest rate cuts affect mortgages?"},
)
question_id = res.json()["data"]["question_id"]

You get back a question_id to poll:

{
  "message": "success",
  "data": {
    "question_id": "0e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b"
  }
}

anonymous_id identifies the reader. Send the same value for the same person, so Miso can keep their history and report on their usage.

2. Fetch the answer

Poll this endpoint until finished is true:

QUESTION_ID=0e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b

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

const url =
  `https://api.askmiso.com/v1/ask/questions/${questionId}/answer`;
const headers = { "X-Api-Key": "YOUR_SECRET_KEY" };

let answer;
while (true) {
  const res = await fetch(url, { headers });
  answer = (await res.json()).data;
  if (answer.finished) break;
  await new Promise((r) => setTimeout(r, 1500));
}

import time

url = f"https://api.askmiso.com/v1/ask/questions/{question_id}/answer"
headers = {"X-Api-Key": "YOUR_SECRET_KEY"}

while True:
    answer = requests.get(url, headers=headers).json()["data"]
    if answer["finished"]:
        break
    time.sleep(1.5)

Poll every 1 to 2 seconds. A typical answer finishes in 12 seconds, after passing through these stages:

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

The response grows as Miso works, so you can show the partial answer while you wait.

Stop on finished. Do not test answer_stage. As the list above shows, it is a sentence for a reader, and Miso translates it into the language of your app. Its wording changes. The finished flag does not.

When it finishes, you get the answer, its sources, and suggested follow-ups:

{
  "data": {
    "finished": true,
    "answer": "Lower rates make mortgages cheaper. [1]",
    "sources": [
      {
        "product_id": "rates-and-mortgages",
        "title": "What rate cuts mean for your mortgage",
        "url": "https://example.com/markets/rates",
        "date": "2026-06-12T00:00:00+00:00",
        "snippet": "The central bank said it expects two cuts…",
        "highlight_text": "two cuts in 2026",
        "boosted": false
      }
    ],
    "followup_questions": [
      "When is the next central-bank meeting?",
      "Should I fix my mortgage now?"
    ]
  }
}

The [1] in the answer is a citation. It points at the first item in sources. Render each one as a link back to your article. See Answer response fields for every field.

If a call fails

Add Miso to your site

The API is the whole platform, but you do not have to build the front end. The Miso SDK gives you the components and it captures interactions for you.

Next steps

1. Integrating Your Data — keep your catalog in sync.
2. API Overview — the conventions every endpoint follows.
3. Answer Metrics — see how your answers perform.