Summary API

The Summary API writes a summary from a set of your articles. You choose the articles with a filter. You tell Miso what to write with your own instructions.

Although the name says "summary", the API can generate many kinds of content from your articles:

• A newsletter or a daily brief.
• A summary of a search result page.
• A topic or company roundup page.
• Key takeaways for a single article.
• Structured JSON for your own front end.

The API is asynchronous. You submit a request, then you poll for the result.

How article selection works

You do not send the article text. Miso reads the articles from your own catalog — the same index the Answer API uses. You select them with fq, a filter query.

published_at:[now-7d TO *]                    the last 7 days
section:"markets"                             one section
product_id:("id-1" OR "id-2")                 specific articles
brand:"Architects Journal" AND type:"news"    combined

If you need to include text that is not in your catalog, pass it as a virtual article.

If no article matches your fq, Miso returns 404 and creates nothing.

Authentication

Every request needs your API key. Pass it as ?api_key=YOUR_KEY or in the X-Api-Key header. Base URL: https://api.askmiso.com.

Write a summary

1. Submit the request

POST /v1/ask/summary

You must supply at least one of instructions, template, or task_id. Most integrations use instructions.

curl -X POST "https://api.askmiso.com/v1/ask/summary" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Summarize the latest news in 3 bullet points.",
    "fq": "published_at:[now-7d TO *]",
    "max_articles": 10
  }'

const res = await fetch("https://api.askmiso.com/v1/ask/summary", {
  method: "POST",
  headers: {
    "X-Api-Key": KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    instructions: "Summarize the latest news in 3 bullet points.",
    fq: "published_at:[now-7d TO *]",
    max_articles: 10
  }),
});
const data = (await res.json()).data;

import requests

res = requests.post(
    "https://api.askmiso.com/v1/ask/summary",
    headers={"X-Api-Key": KEY},
    json={
      "instructions": "Summarize the latest news in 3 bullet points.",
      "fq": "published_at:[now-7d TO *]",
      "max_articles": 10
    },
)
data = res.json()["data"]

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

2. Poll for the summary

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

Poll until finished is true.

curl "https://api.askmiso.com/v1/ask/summaries/$QUESTION_ID/summary" \
  -H "X-Api-Key: $KEY"

const res = await fetch(
  "https://api.askmiso.com/v1/ask/summaries/$QUESTION_ID/summary",
  { headers: { "X-Api-Key": KEY } }
);
const data = (await res.json()).data;

import requests

res = requests.get(
    "https://api.askmiso.com/v1/ask/summaries/$QUESTION_ID/summary",
    headers={"X-Api-Key": KEY},
)
data = res.json()["data"]

{
  "message": "success",
  "data": {
    "question_id": "0e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "finished": true,
    "finish_reason": "success",
    "answer": "- Rates are expected to fall twice this year. [1]",
    "sources": [
      {
        "product_id": "art-20260612-rates",
        "title": "Central bank signals 2026 cuts",
        "url": "https://example.com/markets/rates"
      }
    ]
  }
}

Wait 2–4 seconds before your first poll. A brand-new request is not queryable immediately, and an early poll returns 404.

Get the result in one call

Add ?wait_for_answer=true to the POST. The request then blocks and returns the finished summary.

Use this only for short summaries. The connection can time out after about 60 seconds, and a summary with rules or a large article set often takes longer. For production, use polling.

What the flow looks like

A topic summary filtered with fq:

{
  "anonymous_id": "doc-test",
  "instructions": "Summarize the news about the Linux operating system in 3 bullets.",
  "fq": "tags:Computing",
  "max_articles": 10
}

POST returns only a question id. Poll GET /v1/ask/summaries/{question_id}/summary until finished is true:

"Initializing"
"Generating summary"     finished: true

That request finishes in about 10 seconds and returns 3 sources. The body is the same shape as an answer, so answer, sources, followup_questions, finish_reason and blocked_reason all behave as they do on Answer response fields.

Miso writes the citation as a markdown link inside the summary text, so render the text as markdown.

Request fields

Selecting the articles

Miso retrieves up to max_articles, but sends only the first 25 to the model. A larger max_articles widens the pool for filtering. It does not make the summary longer.

Telling Miso what to write

Caching

Miso caches a result for 24 hours against the tag set of your request — the instructions, filter, format, and article count. If you change any of them, the cache updates on its own.

rules are not part of the cache key. If you request the same content first without rules and then with rules, you can get the earlier cached version. Use force_refresh while you develop your rules.

Response fields

Citations appear in the text as markdown links to the article URL. The sources array lists those articles in the order they are first cited.

Instructions and rules

instructions decide what Miso writes. rules decide what the result must satisfy before Miso returns it. The difference is easiest to see on one topic, run twice over the same catalog.

Instructions only. 34 seconds, 846 words, 6 sources:

{
  "instructions": "Summarize the main technology news.",
  "fq": "tags:Computing",
  "max_articles": 10
}

# Technology News Summary

## Microsoft Expands Cloud Gaming Partnerships Amid Regulatory Scrutiny

Microsoft signed a 10-year agreement with Spanish platform Nware to stream
Microsoft gaming titles, [as reported by
Wikinews](https://en.wikinews.org/wiki/Microsoft%2C_Nware_sign_10-year_cloud_gaming_deal).
The deal came days after UK regulators blocked Microsoft's planned acquisition…

The same request, with one rule. 42 seconds, 58 words, 3 sources:

{
  "instructions": "Summarize the main technology news.",
  "fq": "tags:Computing",
  "max_articles": 10,
  "rules": ["The summary must be under 60 words."]
}

## Technology News Summary

Microsoft signed a [10-year cloud gaming deal with Spanish platform
Nware](https://en.wikinews.org/…), aiming to reassure regulators amid its
contested Activision acquisition. The Netherlands moved to [restrict
semiconductor exports](https://en.wikinews.org/…) on national security
grounds…

The rule cut the output from 846 words to 58. Two details are worth your attention.

%%{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':60,'padding':12}}}%%
flowchart LR
  REQ["`**Your request**
  instructions · fq · rules`"]
  PICK["`Pick the articles
  fq, then max_articles`"]
  GEN["`Write the summary`"]
  JUDGE{"`Every rule
  satisfied?`"}
  OUT["`**Return the summary**`"]
  GIVE["`Return it anyway
  after 3 attempts`"]

  REQ --> PICK --> GEN --> JUDGE
  JUDGE -- yes --> OUT
  JUDGE -- "no, and attempts left" --> GEN
  JUDGE -- "no, 3 attempts used" --> GIVE

  classDef req fill:#f6f7fa,stroke:#c9cfe0,color:#454c69
  classDef work fill:#e8ecfb,stroke:#b9c2ea,color:#22307a
  classDef done fill:#f4effc,stroke:#cdbcf0,color:#40277a
  class REQ req
  class PICK,GEN,JUDGE work
  class OUT,GIVE done

A language model decides whether each rule passed, and the failures are fed back into the next attempt. That loop is why a ruled request takes longer, and why a word count lands close rather than exact.

What rules are good at

Rules work best on word choice, formatting, and style — the things a careful reader can check by looking. Miso judges each rule with a language model, so a rule you can hand to a sub-editor works. A rule that needs counting is weaker.

This request carried three rules:

{
  "instructions": "Summarize the main technology news.",
  "fq": "tags:Computing",
  "max_articles": 6,
  "rules": [
    "Write only bullet points. Do not write paragraphs.",
    "Do not write an introduction or a conclusion.",
    "Always write 'open source', never 'open-source'."
  ]
}

All three held. The result was 7 bullet points and no paragraphs, it opened on the first item with no preamble, and the hyphenated spelling did not appear:

- **Microsoft cloud gaming deal**: Microsoft and Spanish platform Nware signed a
  10-year agreement allowing Nware to stream Microsoft gaming titles, [reports
  Wikinews](https://en.wikinews.org/…); the deal extends to Activision titles if
  Microsoft's acquisition succeeds…

- **Netherlands semiconductor export curbs**: The Dutch government announced
  plans to restrict exports of advanced chip-making equipment…

Expect this to hold most of the time, not every time. The same three rules against the same articles do not always give the same result. A summary can come back with a stray paragraph among the bullets, or with the spelling the rule bans. Check the output, or ask again, when a rule really matters.

Write house style this way: banned and preferred terms, the shape of the output, what to leave out, the tone.

A word count is only approximate

A number is the weak case. The rule below asks for under 60 words, and the summary comes back at 57, 58 or 62 words: close each time, over the line often enough to matter:

{
  "rules": ["The summary must be under 60 words."]
}

Miso does not count the words. It asks a language model whether the rule passes, and when the answer is no, it feeds the failure back and writes the summary again, up to 3 times. That retry is why the ruled request takes about 42 seconds against 34.

So a length rule pulls the summary to roughly the size you asked for — 846 words became 58 — but it does not hold an exact ceiling. If you need one, cut the text on your side.

A rule that cannot be judged is silently passed. If the check itself fails, Miso keeps the summary rather than blocking it. Rules make the summary better. They do not guarantee it.

Rules are not part of the cache key

Both requests above ran with cache_mode: "none". Without it, the second request returns the first result, word for word, because the cache key covers the instructions, the filter, the format and the article count — but not the rules.

Send the same request twice with caching on, and add a rule the second time. The first takes about 39 seconds. The second returns the same words, character for character, in about 2 seconds, and the rule never runs.

Use cache_mode: "none" or force_refresh while you develop your rules.

What the other fields do

Each example below uses the same catalog.

fq chooses the articles

fq is the filter that decides which articles Miso reads. It is the same syntax the search endpoints use, so tags:Computing here means what it means there. See Filter Syntax (fq).

Miso then reads up to max_articles of them, newest and most relevant first.

format changes the markup

format: "html" returns HTML instead of Markdown:

<h2>Technology News Summary</h2>
<h3>Microsoft Signs 10-Year Cloud Gaming Deal</h3>
<p>Microsoft and Spanish streaming platform Nware reached a 10-year agreement to
allow Nware to stream Microsoft gaming titles,
<a href="https://en.wikinews.org/wiki/Microsoft%2C_Nware_sign_10-year_cloud_gaming_deal">reports
Wikinews</a>.</p>

url_template rewrites every link

Put {url} where the article address belongs, and Miso rewrites each citation through it:

{
  "url_template": "https://example.com/track?to={url}&utm_source=miso"
}

[reports Wikinews](https://example.com/track?to=https%3A%2F%2Fen.wikinews.org%2Fwiki%2FMicrosoft%252C_Nware_sign_10-year…&utm_source=miso)

The article URL is percent-encoded for you, so it survives as one parameter.

enable_citations: false removes the links

The same request without citations returns plain prose:

Microsoft launched a program to pay businesses for switching to its Windows Live
Search engine, reports Wikinews. The initiative offers companies between $2 and
$10 per computer annually, plus $25,000 just for enrolling.

Use it when your front end adds its own links, or when you asked for JSON.

virtual_articles adds text that is not in your catalog

Send up to 10 articles inline. Miso treats them like catalog articles, and they can be cited:

{
  "instructions": "Summarize what is new, and mention the editor's note.",
  "fq": "tags:Computing",
  "max_articles": 3,
  "virtual_articles": [
    {
      "title": "Editor's note: our technology coverage",
      "description": "Wikinews will publish hands-on reviews of new Linux releases.",
      "url": "https://example.com/editors-note"
    }
  ]
}

The summary then cites four sources: the three catalog articles, and the editor's note.

Each virtual article needs description or html. Without one, the request fails:

{
  "detail": [
    {
      "loc": ["body", "virtual_articles", 0, "__root__"],
      "msg": "At least one of 'html' or 'description' must be provided",
      "type": "value_error"
    }
  ]
}

Examples

Simple: a weekly brief

{
  "instructions": "Write a 5-bullet brief of this week's top stories.",
  "fq": "published_at:[now-7d TO *]",
  "max_articles": 20
}

Key takeaways for one article

Scope the filter to a single article, and turn citations off because the reader is already on that page.

{
  "instructions": "List the 3 key takeaways for a busy reader.",
  "fq": "product_id:(\"art-20260612-rates\")",
  "enable_citations": false
}

Structured JSON for your front end

Ask for json and describe the exact shape you want. The result arrives as a JSON string in answer, so parse it on your side.

{
  "instructions": "Return short_summary and long_summary keys.",
  "fq": "section:\"football\" AND published_at:[now-1d TO *]",
  "format": "json",
  "rules": [
    "short_summary must be 200 characters or fewer",
    "long_summary must be 350 words or fewer",
    "Output must be valid JSON with exactly those two keys"
  ]
}

Enforcing house style with rules

{
  "instructions": "Summarize the latest coverage of this company.",
  "fq": "companyName:\"Example Corp\"",
  "max_articles": 100,
  "rules": [
    "Every bullet point must name the company",
    "Each section must have at least one bullet point",
    "There must be no introduction and no closing text"
  ]
}

Writing in another language

There is no language field. State the language in your instructions, and add a rule to enforce it.

{
  "instructions": "Fasse die aktuellen Meldungen in drei Punkten zusammen.",
  "fq": "published_at:[now-1d TO *]",
  "rules": ["Die gesamte Ausgabe muss auf Deutsch sein."]
}

Adding your own text

Use virtual_articles for text that is not in your catalog — a press release, a data feed, or an unpublished draft. Miso treats them like catalog articles for citations and sources. They do not count toward max_articles. The limit is 10.

{
  "instructions": "Summarize all of the provided articles.",
  "virtual_articles": [
    {
      "title": "Quantum computing breakthrough",
      "url": "https://example.com/quantum",
      "html": "<p>Researchers achieved 1000-qubit stability.</p>"
    }
  ]
}

Ready-made templates

Two templates ship with the API. Both are opinionated. For most cases, your own instructions give a better result.

{
  "template": "newsletter_v1",
  "fq": "published_at:[now-7d TO *]",
  "template_parameters": {
    "briefing_name": "Markets Brief",
    "focus_topic": "interest rates",
    "max_headlines": 5,
    "tone": "professional"
  }
}

newsletter_v1 accepts briefing_name, focus_topic, max_headlines (1–20), target_audience, tone, include_quick_hits, and opening_style. newsvault accepts summary_type and focus_topic.

Notes and limits

• The model sees 25 articles. max_articles controls how many are retrieved, not how many are summarized.
• rules cost time. Each failed check triggers a rewrite, up to 3 times. A request with rules can take longer than a synchronous wait allows.
• format: "json" always runs a rule check, because valid JSON is itself a rule.
• Unknown fields are ignored, not rejected.
• Some features are enabled per app. Scheduled refresh of permanent summaries, saved task configurations, and pregenerated related questions are set up by Miso. Contact your Miso representative to enable them.