Topics APIGive every topic a clear identity.

Start with the job your labels must do

A topic is a reusable concept that helps people organize or retrieve content. A tag is often a lightweight label attached during publishing. An entity identifies something specific, such as an organization or a place. Treating these as separate fields makes it easier to ask whether a story is about energy policy, mentions an energy company, or belongs in an editor’s weekend collection.

Before choosing a model or endpoint, write down the decisions the labels will support. A navigation menu may need one broad category. An archive may need several detailed subjects. A reporting workflow may need a human review queue. The same document can serve all three purposes without forcing every purpose into one label.

Design a small, durable contract

Give each concept a stable ID and keep the display label separate. Include a short definition, an optional parent, a taxonomy version, and the language of the label. An identifier should continue to mean the same concept when you correct a spelling or translate its name.

Keep the topic catalog separate from document assignments. The catalog defines what a concept means; an assignment records why that concept was applied to one piece of content. This separation lets you improve a classifier without silently rewriting the vocabulary underneath existing integrations.

Make uncertainty useful

A classifier can return an allowed label while misunderstanding the text. Decide how your application will represent uncertainty, insufficient context, and content outside the taxonomy. An explicit review state is more useful than a plausible but unsupported label.

Use a small collection of representative documents to inspect mistakes. Include short items, overlapping categories, multiple languages, and examples that should receive no label. Review the failure cases with the people who use the taxonomy; a technically valid response is only the beginning of a useful result.

Plan changes before the first integration

Publish a change policy for renamed labels, merged concepts, and retired IDs. Keep a mapping when you migrate from one taxonomy version to another, and distinguish exact replacements from approximate matches. A consuming application should be able to explain why an old record displays differently.

Begin with a compact vocabulary and expand when a repeated reader need warrants it. Every new label creates work: definitions, examples, review rules, and migration decisions. A smaller taxonomy that people understand often makes a stronger foundation than a large list with overlapping meanings.

An illustrative record

This example highlights fields worth discussing when you design your own contract. Define their meanings, allowed values, and review rules before an application relies on them.

{
  "document_id": "example-article",
  "taxonomy_version": "demo-v1",
  "topics": [
    {
      "topic_id": "ai.language-models",
      "label": "Language models"
    }
  ],
  "review_status": "needs_review"
}

Illustrative schema and example values; adapt them to your data and review process.

Questions about Topics API