Create Topic
Create a topic in a domain, with an optional description.
curl --request POST \
--url https://api.aiclicks.io/api/v1/topics \
--header 'Authorization: Bearer ak_live_xxx' \
--header 'Content-Type: application/json' \
--data '{
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"name": "Migration",
"description": "Prompts about moving data from other tools"
}'
import httpx, os
resp = httpx.post(
"https://api.aiclicks.io/api/v1/topics",
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
json={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"name": "Migration",
"description": "Prompts about moving data from other tools",
},
)
resp.raise_for_status()
print(resp.json()["data"]["id"])
const resp = await fetch("https://api.aiclicks.io/api/v1/topics", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AICLICKS_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
domain_id: "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
name: "Migration",
description: "Prompts about moving data from other tools",
}),
});
const { data } = await resp.json();
console.log(data.id);
{
"data": {
"id": "e3f4a5b6-7c8d-4e9f-a0b1-c2d3e4f5a6b7",
"name": "Migration",
"description": "Prompts about moving data from other tools",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"created_at": "2026-11-09T10:00:11.118000+00:00",
"updated_at": "2026-11-09T10:00:11.118000+00:00",
"archived": false
},
"generated_at": "2026-11-09T10:00:11.218000+00:00"
}
{
"detail": "A topic named "Migration" already exists in this domain."
}
{
"detail": "Access denied: User is not a member of the team that owns this domain"
}
Creates one topic in a domain. Topics put prompts into groups. After you create the topic, you can put prompts in it with POST /api/v1/prompts/topics, POST /api/v1/prompts or POST /api/v1/prompts/update.
Topic names are unique in a domain. If a topic with the same name exists, the call returns 409.
Authorizations
Your API key in the format Bearer ak_live_<your-key>. Create a key in the dashboard under Settings → Developers. The key must have access to the team that owns domain_id.
Must be application/json.
Body parameters
UUID of the domain for the new topic.
The topic name. The API removes spaces at the start and end. The name must have 1 to 100 characters.
An optional description of the topic. Default null.
Response
The new topic. It has id, name, description, domain_id, created_at and updated_at. It can also have other stored columns, for example archived.
UUID of the new topic. Use this value in topic_ids.
ISO-8601 time when the server made this response.
Side effects
- No prompt credit is used.
- The API clears the cache of
GET /api/v1/prompts,GET /api/v1/tagsandGET /api/v1/topicsfor the domain.
Errors
The API key is missing, malformed or revoked.
The caller is not a member of the team of the domain, or the API key has no access to this domain. The plan of the team can also not include API access.
A topic with the same name exists in the domain.
The body is not valid. For example, name is empty or has more than 100 characters.
You sent too many requests. Read the Retry-After header to know how long to wait.