API Overview

Miso is one REST API on https://api.askmiso.com. You send JSON. You get JSON back. You authenticate with an API key.

You give Miso your content. Miso indexes it and atomizes it. You then ask questions against it, search it, recommend from it, or let an AI agent read it. Miso records every call, so you can measure what people ask and what they read.

How Miso fits together

%%{init: {'theme':'base','themeVariables':{
'fontFamily':'IBM Plex Sans, ui-sans-serif, system-ui','fontSize':'14px',
'lineColor':'#9aa3c0','clusterBkg':'transparent','clusterBorder':'#d3d8e8','titleColor':'#8b93ad'
},'flowchart':{'curve':'basis','nodeSpacing':20,'rankSpacing':78,'padding':12}}}%%
flowchart LR
  subgraph SRC["YOUR SIDE"]
    direction TB
    CMS["`Your content
    REST · SFTP · crawler · webhook`"]
    SITE["`Your site
    Miso SDK or your own frontend`"]
  end

  subgraph MISO["MISO"]
    direction TB
    DATA(["Data APIs"])
    IDX["`Index
    text · embeddings`"]
    ATOM["`Atomize
    knowledge graph`"]
    SERVE(["Serving APIs"])
  end

  subgraph OUT["WHAT YOU BUILD"]
    direction TB
    ASK["Answers"]
    SEARCH["Search & Explore"]
    REC["Recommendation"]
    FEED["News Feed"]
    SUM["Summary"]
    LB["LightBox"]
    MCP["MCP for AI agents"]
  end

  CMS --> DATA
  SITE --> DATA
  DATA --> IDX --> SERVE
  DATA --> ATOM --> SERVE
  SERVE --- ASK
  SERVE --- SEARCH
  SERVE --- REC
  SERVE --- FEED
  SERVE --- SUM
  SERVE --- LB
  SERVE --- MCP

  classDef src fill:#f6f7fa,stroke:#c9cfe0,color:#454c69
  classDef hub fill:#3148be,stroke:#3148be,color:#ffffff,stroke-width:0px
  classDef core fill:#e8ecfb,stroke:#b9c2ea,color:#22307a
  classDef outbox fill:#f4effc,stroke:#cdbcf0,color:#40277a
  class CMS,SITE src
  class DATA,SERVE hub
  class IDX,ATOM core
  class ASK,SEARCH,REC,FEED,SUM,LB,MCP outbox

Miso does two things with each record, and they run in parallel:

Index. Miso stores the full text and computes embeddings. This is what makes hybrid search and retrieval work.
Atomize. Miso extracts the entities, the topics, and the relations between them into a knowledge graph. This is what lets Miso reason across many articles instead of one at a time.

Integrate in three steps

1. Send your content

Upload your catalog with the Data APIs. Most customers POST to /v1/products from their CMS. Miso also accepts SFTP drops, a crawler, and webhooks. See Integrating Your Data for each option.

2. Put Miso on your site

Deploy the Miso SDK. It gives you the front-end components and it captures interactions for you. This is the fastest path, and it is what most customers use.

If you build your own front end, call the API directly and send the interactions yourself with POST /v1/interactions. That endpoint is the only one a publishable key can reach, so you can call it from the browser.

3. Check your data in Dojo

Open your Dojo dashboard. Dojo shows what Miso holds for you, how your answers perform, and where users click. You also configure your app there. See Answer Metrics.

What is in the API

Group	What it does	Where to start
Data APIs	Upload and delete products, users, and interactions.	Integrating Your Data · Product Schema
GenAI APIs	Answers, summaries, tagging, user history, and Explore.	Explore Questions
Search & Rec APIs	Search, recommendations, and bulk reads, without an answer.	Search & Recommendation
Experiment APIs	Report experiment events back to Miso.	API Reference

News Feed and LightBox are built on these same APIs. Ask your Miso representative how to enable them for your app.

Quick example

Ask a question against your content with a single call (authenticate with ?api_key=YOUR_SECRET_KEY or the X-API-KEY header):

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 are the latest rate-cut expectations?"
  }'

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

Then poll GET /v1/ask/questions/{question_id}/answer for the result. See Getting started for the full flow.

API conventions

The same rules apply to every endpoint.

Two keys, two jobs

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

Key	Where it belongs	What it can reach
Publishable	Browser code. It is expected to be visible.	`POST /v1/interactions` only.
Secret	Your server. Never ship it to a browser.	Every endpoint.

A publishable key on any other endpoint returns 403. Miso also refuses a publishable key that arrives with a robot user-agent. See Authentication.

Every response has the same shape

A successful call returns a message and a data field:

{
  "message": "success",
  "data": {}
}

An error keeps message and explains what went wrong. A failed upload also carries errors, and puts one entry per bad record in data.

The GenAI APIs use a second shape for a malformed request body. It comes from the request validator, and it names the field:

{
  "detail": [
    {
      "loc": ["body", "__root__"],
      "msg": "Either 'template' or 'instructions' or 'task_id' must be provided",
      "type": "value_error"
    }
  ]
}

Read detail when it is present, and message otherwise.

Code	What it means
`200`	Success. On an upload, still read `errors` in the body.
`401`	The key is missing or wrong.
`403`	A publishable key on a secret-key endpoint, or a blocked robot.
`404`	Unknown id. A question that belongs to another app is also `404`.
`422`	The records did not pass validation. `data` lists each problem.
`429`	Too many requests. Slow down and retry.
`500`	A fault on Miso's side. Retry, then contact Miso.

Uploads validate as a batch

If one record fails validation, Miso rejects the whole batch and returns 422. Nothing is written. Fix the records that data names, then send the batch again.

One rule catches most failures: Miso rejects any top-level field it does not define. Everything of your own belongs in custom_attributes. Add dry_run=1 to validate a batch without writing it.

Uploads are asynchronous

POST /v1/products and POST /v1/users return a task id:

{
  "message": "success",
  "data": {
    "task_id": "eyJpdiI6IktXZ2Voc0UwSzZSd1pKMWYySjJZNXc9PSIs…"
  }
}

Poll GET /v1/products/_status/{task_id} (or /v1/users/_status/{task_id}) until it stops reporting pending. Allow at least a minute: a single-record batch takes about 51 seconds to finish.

Interactions do not work this way. POST /v1/interactions answers immediately, so you can call it on every click.

Answers are asynchronous too

Ask a question, then poll for the answer:

POST /v1/ask/questions returns a question_id.
GET /v1/ask/questions/{question_id}/answer returns the answer so far.
Stop when finished is true.

Poll on finished. Do not test answer_stage. answer_stage is a sentence for a reader, such as "Doing more research, this may take a little longer", and Miso translates it into the language of your app. Its wording changes. The finished flag does not.

Poll every 1 to 2 seconds. Answers finish in about 12 to 14 seconds.

Miso does not call you back

There are no webhooks and no streaming endpoint for answers. Every result is retrieved by a poll, as described above.

Rate limits

Miso limits requests per API key. Over the limit, you get 429. Retry with an exponential backoff.

Two things are worth planning for. Bulk endpoints have a tighter limit than the rest. And your exact limit depends on your plan and your region, so ask your Miso representative before you build a large backfill.

Events & Custom JS

Authentication