Create a topic summary

​

Summarize a set of your articles. You choose the articles with fq, and you say what to write with instructions.

Despite the name, this endpoint can generate many kinds of content: a newsletter, a search-results summary, a topic roundup, key takeaways for one article, or structured JSON for your own front end.

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

Miso reads the articles from your own catalog — you do not send article text. If nothing matches your fq, the call returns 404 and creates nothing.

End-to-end

1. Submit.

curl -X POST "https://api.askmiso.com/v1/ask/summary" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{ "instructions": "Summarize this week in 3 bullets.",
        "fq": "published_at:[NOW-7DAYS TO NOW]",
        "max_articles": 10 }'

2. You get an id to poll.

{
  "message": "success",
  "data": {
    "question_id": "57aeb083-b943-43b1-86ab-b6108788dd50",
    "pipeline_version": "v2"
  }
}

3. Poll GET /v1/ask/summaries/{question_id}/summary until finished is true. Wait 2-4 seconds before the first poll, or it returns 404. 

{
  "message": "success",
  "data": {
    "finished": true,
    "answer": "- Rates are expected to fall twice this…",
    "sources": [
      { "product_id": "art-20260612-rates",
        "title": "Central bank signals 2026 cuts" }
    ]
  }
}

Get it in one call

Add ?wait_for_answer=true and the finished summary comes back inline. Use it only for short summaries: the connection can time out after about 60 seconds, and a summary with rules often takes longer. For production, poll.

Selecting the articles

fq is a filter query over your catalog:

published_at:[NOW-7DAYS TO NOW]          the last 7 days
section:"markets"                        one section
product_id:("id-1" OR "id-2")            specific articles
brand:"Example" AND type:"news"          combined

max_articles controls how many are retrieved, not how many are summarized — the model sees the first 25. A larger value widens the pool for relevance_instruction to filter.

Use virtual_articles for text that is not in your catalog.

See the examples on this page for rules, JSON output, other languages and tracked links.

Query Parameters
  • wait_for_answer
    Type: boolean

    If true, block until the summary is ready and return it inline instead of a poll id.

Body·
required
application/json

Summarize a set of articles. Provide either a template or custom instructions.

  • anonymous_id
    Type: string

    The anonymous visitor.

  • fl
    Type: array string[]

    Fields to return for each source article.

  • force_refresh
    Type: boolean

    Regenerate and overwrite the cached summary instead of returning a cached result.

  • format
    Type: string enum

    Output format of the generated summary.

    values
    • markdown
    • html
    • json
  • fq
    Type: string

    Selects the articles to summarize (Elasticsearch query-string syntax (Lucene)). Every matching catalog article — up to max_articles — is included in one summary.

    Examples:

    • "section:\"markets\"" — the markets section
    • "tags:\"interest rates\"" — a topic
    • "section:\"markets\" AND published_at:[NOW-7DAYS TO NOW]" — this week's articles (newsletter)
    • "rating:[4 TO *]" — numeric range
  • instructions
    Type: string

    Custom instructions for the summary (tone, length, structure…). Provide this or template.

  • max_articles
    Type: integer
    min:  
    1
    max:  
    200

    Maximum number of matching articles to include in the summary.

  • relevance_instruction
    Type: string | null

    Per-article relevance filter: each candidate is kept only if it satisfies this (strict LLM check). e.g. "Keep only if interest-rate policy is a primary subject, not a passing mention."

  • rules
    Type: array string[]

    Rules the summary must satisfy; it is regenerated up to 3× to meet them. e.g. ["Must be under 200 words", "Each article must be cited"].

  • template
    Type: string | null enum

    A built-in summary template. Provide this or instructions.

    values
    • newsletter_v1
    • newsvault
  • url_template
    Type: string

    Template applied to every link in the summary — use it to add click-tracking params, e.g. https://example.com{url}?utm_source=newsletter.

  • user_hash
    Type: string

    Hash of user_id/anonymous_id with your Secret API Key — send when calling from the browser with a Publishable key.

Responses
  • application/json
Request Example for post/v1/ask/summary
curl 'https://api.askmiso.com/v1/ask/summary?api_key=YOUR_SECRET_TOKEN' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "fq": "section:\"markets\" AND published_at:[NOW-7DAYS TO NOW]",
  "max_articles": 15,
  "instructions": "Write a concise newsletter intro summarizing the week'\''s top market stories.",
  "format": "html",
  "url_template": "https://example.com{url}?utm_source=newsletter"
}'

{
  "data": {
    "question_id": "57aeb083-b943-43b1-86ab-b6108788dd50",
    "pipeline_version": "v2"
  }
}

Accepted — poll the answer endpoint with the returned question_id.