REST API: topics

Topics are agent-scoped resources. To start a curation job, read the agent's topics and their statistics. Then create, update, merge, or delete only the records that your policy selects. Keep the agent identifier separate from the topic identifier. Do not build a merge or a deletion from display text alone. Labels can look similar, and labels can change over time.

Use similar-topic results as a review aid, not an automatic merge instruction. In a safe workflow, you record the candidate topics, apply the merge, then read the list again before you proceed. Topic statistics have their own bounded query behavior and are not a substitute for all-conversation reporting. If your question is about performance across many conversations, use the Analytics guides instead.

Topic mutations require a trusted backend. Create and update need a write-capable key, while merge and delete require the stricter admin scope. Validate the outgoing payload against the generated reference. Show API validation errors to the operator. Keep enough context to undo an incorrect curation decision through your own process.

Refusals

Every route on this page reads the agent in the path before it touches a topic. A refusal therefore reports the agent, not the topic.

• 404 AGENT_NOT_FOUND — the agent is not in your organization.
• 410 AGENT_UNAVAILABLE — the agent waits for deletion. Its topics are frozen: read, create, update, delete, and merge are all refused while the agent sits in the grace window. Call POST /agents/{id}/cancel-delete first, then retry.
• 404 NOT_FOUND — the topic id is not under the agent in the path. POST /agents/{id}/topics/merge applies this rule to the target topic and to every source topic, so a merge cannot move a topic from one agent to another.

A merge deletes its source topics. A second merge that names the same sources therefore answers 404 NOT_FOUND, not 200. Read the topic list again before you retry a merge that timed out.