Skip to content
Chatvia Docs
On this page

API reference

Topics

Get in touch: Ahmad Mayahi, creator of Chatvia, Spectra and Shakomako

These endpoints decide which topics an agent's conversations are tagged with. Chatvia analyzes conversations and tags them with the matching topics from the agent's list, such as "Billing & Payments" or "Shipping". The tags feed the topic charts in Analytics.

For example, a shop that starts selling gift cards can add a "Gift cards" topic to its support agent, so next month's report shows how many chats were about them.

There are two kinds of topics:

  • System topics come with Chatvia and are shared by every workspace. You can attach and detach them, but not rename them.
  • Workspace topics are your own. You create them here or in the dashboard, and you can rename them.

Read the overview first for the base URL, keys, errors and paging.

Who can call these endpoints: the owner, or a teammate with Manage topics.

The topic object

json
{
  "id": "0199f440-9e0f-7a1b-8c2d-3e4f5a6b7c8d",
  "topic": "Gift cards",
  "description": "Buying, sending, redeeming or checking the balance of gift cards.",
  "is_system": false,
  "created_at": "2026-10-25T14:00:00+00:00"
}
Field Type Meaning
id string The topic's id.
topic string The topic's name.
description string What conversations the topic covers. The AI model that tags conversations reads it, so be specific.
is_system boolean true for a built-in topic, which can't be renamed.
created_at string When the topic was created.

List topics

Returns the agent's topics, newest first.

text
GET /api/v1/agents/{agent}/topics
Query parameter Type Default Notes
scope string agent agent lists the topics attached to the agent. available lists every topic you could attach: the system topics and your workspace's own.
per_page, cursor See Pagination.
bash
curl "https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/topics?scope=available" \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [topic, …], "next_cursor": … }.

Add a topic

Attaches an existing topic to the agent, or creates a new workspace topic and attaches it.

text
POST /api/v1/agents/{agent}/topics

Send either topic_id, or topic and description:

Body field Type Required Notes
topic_id string to attach The id of a system topic or one of your own. Can't be sent with topic or description.
topic string to create The new topic's name, up to 120 characters.
description string to create Up to 255 characters.

To attach an existing topic:

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/topics \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topic_id": "0199f440-9e0f-7a1b-8c2d-3e4f5a6b7c8d" }'

To create a new one:

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/topics \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Gift cards",
    "description": "Buying, sending, redeeming or checking the balance of gift cards."
  }'

The answer is 201 Created with { "data": topic }.

Update a topic

Renames one of your workspace topics or changes its description. The topic must be attached to the agent in the path.

text
PATCH /api/v1/agents/{agent}/topics/{topic}
Body field Type Required Notes
topic string yes Up to 120 characters.
description string yes Up to 255 characters.
bash
curl -X PATCH https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/topics/0199f440-9e0f-7a1b-8c2d-3e4f5a6b7c8d \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "topic": "Gift cards and vouchers", "description": "Buying, redeeming or checking the balance of gift cards and vouchers." }'

The answer is { "data": topic }. A system topic is a 403. A topic the agent doesn't have is a 404.

A workspace topic can be attached to several agents. Renaming it renames it for all of them.

Remove a topic

Detaches the topic from the agent.

text
DELETE /api/v1/agents/{agent}/topics/{topic}
bash
curl -X DELETE https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/topics/0199f440-9e0f-7a1b-8c2d-3e4f5a6b7c8d \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content. A workspace topic that no agent uses any more is deleted. System topics stay available.

Search guides, settings and commands.