Tag a document

Submit a document for classification. Returns a tagging_id to poll.

{tag_set} selects the taxonomies. Miso ships with iptc_iab. An unknown tag set returns 404.

The API is stateless — it classifies the text you send and never reads your catalog, so send the same title and body you show readers.

---

End-to-end

1. Submit the document.

BASE=https://api.askmiso.com

curl -X POST "$BASE/v1/ask/tagging/iptc_iab" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "title": "Central bank signals two rate cuts",
    "content": "The bank expects to lower rates twice th…"
  }'

2. You get an id back.

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

3. Poll until it finishes.

TAGGING_ID=0e1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b

curl "$BASE/v1/ask/tagging/iptc_iab/$TAGGING_ID" \
  -H "X-Api-Key: $KEY"

{
  "message": "success",
  "data": {
    "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"
            }
          ]
        },
        {
          "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"
        }
      ]
    }
  }
}

4. Store what you need. Take the first IPTC theme as the primary category. Use model_agreement for a hard cut — 3/3 means every model that answered agreed, so it is safe to apply automatically; send 2/3 to an editor.

---

Skip the polling loop

For an interactive "tag this now" button, add ?wait_for_answer=true and the finished tags object comes back in this call:

curl -X POST \
  "$BASE/v1/ask/tagging/iptc_iab?wait_for_answer=true" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{ "title": "...", "content": "..." }'

Use it for one document at a time. For a backfill, submit everything first, then poll.

---

Caching

Miso caches each result against the tag set, the title and the content, so a repeat request for an unchanged document returns the cached tags. Re-tagging is automatic: Miso classifies again when you edit the document, and when Miso updates the tag set.