Content Tagging

The Tagging API classifies a document against standard content taxonomies. You send a title and body text. Miso returns the topics, entities, and keywords for that document.

Common uses:

• Add IPTC or IAB categories to an article.
• Route content to the right section or feed.
• Build topic pages and related-content links.

The API is stateless. You pass the text you want to tag. Miso does not read your content index, and it does not store the document.

Tag sets

A tag set is a named group of taxonomies. The URL path selects it: /v1/ask/tagging/{tag_set}.

Miso ships with one tag set, iptc_iab. It tags against two industry taxonomies:

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

The API key on a request controls access and usage only. It does not change the tag set or the result.

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.

Tag a document

Tagging is a two-step flow. First you submit the document. Then you poll for the result.

1. Submit the document

POST /v1/ask/tagging/{tag_set}

curl -X POST "https://api.askmiso.com/v1/ask/tagging/iptc_iab" \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Central bank signals two rate cuts in 2026",
    "content": "The central bank said it expects two cuts..."
  }'

const res = await fetch("https://api.askmiso.com/v1/ask/tagging/iptc_iab", {
  method: "POST",
  headers: {
    "X-Api-Key": KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Central bank signals two rate cuts in 2026",
    content: "The central bank said it expects two cuts..."
  }),
});
const data = (await res.json()).data;

import requests

res = requests.post(
    "https://api.askmiso.com/v1/ask/tagging/iptc_iab",
    headers={"X-Api-Key": KEY},
    json={
      "title": "Central bank signals two rate cuts in 2026",
      "content": "The central bank said it expects two cuts..."
    },
)
data = res.json()["data"]

You get back a tagging_id to poll:

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

If the {tag_set} does not exist, Miso returns 404.

To get the result in one call, add ?wait_for_answer=true to the POST. The request then blocks until tagging is complete and returns the result directly.

2. Get the tags

GET /v1/ask/tagging/{tag_set}/{tagging_id}

Poll this endpoint until finished is true.

curl "https://api.askmiso.com/v1/ask/tagging/iptc_iab/$TAGGING_ID" \
  -H "X-Api-Key: $KEY"

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

import requests

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

{
  "message": "success",
  "data": {
    "tag_set": "iptc_iab",
    "stage": "finished",
    "finished": true,
    "finish_reason": "success",
    "tags": {
      "tag_set": "iptc_iab",
      "taxonomies": [
        {
          "taxonomy": "iptc",
          "themes": [
            {
              "code": "medtop:20000350",
              "label": "economy, business and finance",
              "confidence": 0.91,
              "model_agreement": "3/3"
            }
          ]
        },
        {
          "taxonomy": "iab",
          "themes": [
            {
              "code": "432",
              "label": "Personal Finance",
              "confidence": 0.78,
              "model_agreement": "2/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"
        }
      ]
    }
  }
}

The poll returns 404 in three cases:

• The tagging_id does not exist.
• The tagging_id belongs to a different app.
• The {tag_set} does not match the one that created the id.

Result fields

The tags object holds three lists: taxonomies, entities, and keywords.

Themes (per taxonomy)

Each entry in taxonomies has a taxonomy name and a list of themes.

Entities

Keywords

How the tags are chosen

Miso sends the document to several models. Each model tags it against the taxonomy on its own. Miso then merges the results with a cross-vote.

• Miso keeps a topic when enough models agree on it.
• confidence is the mean over the models that agreed.
• model_agreement shows the vote, for example 3/3.

Miso validates every code against the taxonomy. If a code is a near-miss, Miso corrects it to the closest valid code. If a code has no match, Miso drops it.

Miso extracts entities and keywords once, then votes across the models. It normalizes entity names and drops social-platform handles. If a keyword repeats an entity, Miso removes the keyword.

Caching

Miso caches each result against the tag set, the title, and the content. A repeat request for an unchanged document returns the cached tags, so you can call the API again safely.

Re-tagging is automatic. Miso classifies the document again when you edit the title or the body, and when Miso updates the tag set.