Classify a document against standard content taxonomies. You send a title and body text; Miso returns topics, entities and keywords.

Use it to add IPTC or IAB categories to an article, route content to the right section or feed, or build topic pages and related-content links.

How it works

The API is stateless: you pass the text you want tagged. Miso does not read your content index and does not store the document.

Several models classify the document independently against each taxonomy, then Miso merges them with a cross-vote. A topic is kept when enough models agree. confidence is the mean over the agreeing models, and model_agreement shows the vote (for example 2/3 = two of the three models that answered agreed). Every code is validated against the taxonomy; a near-miss is corrected to the closest valid code, and an unmatchable code is dropped.

Tag sets

A tag set is a named group of taxonomies, selected by the URL path. Miso ships with iptc_iab, which tags against:

• IPTC Media Topics — a subject taxonomy for news and media
• IAB Content Taxonomy (v3.1) — a taxonomy for content and advertising

Two-step flow

1. POST /v1/ask/tagging/{tag_set} returns a tagging_id.
2. GET /v1/ask/tagging/{tag_set}/{tagging_id} — poll until finished is true.

Add ?wait_for_answer=true to the POST to get the result in one call.

Caching

Results are cached against the tag set, title and content. Re-tagging is automatic: changing any of them invalidates the entry, so an edited document is always classified again.

---

Examples

Every example below classifies against the iptc_iab tag set. Swap the path segment if Miso has set up another tag set for you.

Example 1 — Tag an article (simplest)

Submit the document:

POST /v1/ask/tagging/iptc_iab
{
  "title": "Central bank signals two rate cuts in 2026",
  "content": "The central bank said it expects to lower…"
}

You get an id to poll:

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

Poll GET /v1/ask/tagging/iptc_iab/0e1f2a3b-... until finished is true:

{
  "message": "success",
  "data": {
    "tag_set": "iptc_iab",
    "finished": true,
    "finish_reason": "success",
    "tags": {
      "taxonomies": [
        {
          "taxonomy": "iptc",
          "themes": [
            {
              "code": "medtop:20000350",
              "label": "economy, business and finance",
              "confidence": 0.91,
              "model_agreement": "3/3"
            }
          ]
        }
      ],
      "entities": [
        {
          "name": "Federal Reserve",
          "kind": "organization",
          "relevance": 0.9,
          "role": "primary",
          "model_agreement": "3/3"
        }
      ],
      "keywords": [
        {
          "keyword": "interest rates",
          "relevance": 0.85,
          "model_agreement": "3/3"
        }
      ]
    }
  }
}

Example 2 — Get the tags in one call

For a CMS "tag this now" button, skip the polling loop:

POST /v1/ask/tagging/iptc_iab?wait_for_answer=true
{
  "title": "Inside the fight to save the high street",
  "content": "Across a dozen market towns, independent r…"
}

The response carries the finished tags object directly. Use this only for a single interactive document. For a backfill, submit everything first, then poll.

Example 3 — Pick one category to store

themes is ranked. For a single primary category, take the first IPTC theme and apply your own confidence floor:

{
  "taxonomy": "iptc",
  "themes": [
    {
      "code": "medtop:20000350",
      "label": "economy, business and finance",
      "confidence": 0.91,
      "model_agreement": "3/3"
    },
    {
      "code": "medtop:20000385",
      "label": "market and exchange",
      "confidence": 0.64,
      "model_agreement": "2/3"
    }
  ]
}

model_agreement is the more useful signal for a hard cut. 3/3 means every model that answered agreed; 2/3 means one disagreed. A common rule is to store themes at 3/3 automatically and route 2/3 to an editor for review.

Example 4 — Let the cache work for you

Miso caches each result against the tag set, the title and the content, so you can call the API again for the same document without paying twice.

Re-tagging is automatic. Miso classifies the document again when you edit the title or the body, and when Miso updates the tag set — you do not have to clear anything.

Example 5 — Backfill an archive

For a bulk run, submit every document first, then poll. Do not wait for each one in turn.

1. POST each document and keep its tagging_id.
2. Poll each id until finished is true.
3. Store code and label per taxonomy, plus entities for your topic pages.

Send the same title and content you show readers. The API is stateless and never reads your catalog, so anything you leave out is invisible to the tagger.