Create Tag
Create a tag in a domain, with an optional color. Requires the admin, co-admin or editor role.
curl --request POST \
--url https://api.aiclicks.io/api/v1/tags \
--header 'Authorization: Bearer ak_live_xxx' \
--header 'Content-Type: application/json' \
--data '{
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"name": "Pricing",
"color_id": "green"
}'
import httpx, os
resp = httpx.post(
"https://api.aiclicks.io/api/v1/tags",
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
json={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"name": "Pricing",
"color_id": "green",
},
)
resp.raise_for_status()
print(resp.json()["data"]["id"])
const resp = await fetch("https://api.aiclicks.io/api/v1/tags", {
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: "Pricing",
color_id: "green",
}),
});
const { data } = await resp.json();
console.log(data.id);
{
"data": {
"id": "d4e5f6a7-8b9c-4d0e-a1f2-b3c4d5e6f7a8",
"name": "Pricing",
"color_id": "green",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3"
},
"generated_at": "2026-11-09T10:00:11.218000+00:00"
}
{
"detail": "Only team admins, co-admins, and editors can manage tags"
}
{
"detail": "A tag named "Pricing" already exists in this domain."
}
{
"detail": "Unknown tag color: lime"
}
Creates one tag in a domain. After you create the tag, you can attach it to prompts with POST /api/v1/prompts/tags, POST /api/v1/prompts or POST /api/v1/prompts/update.
Tag names are unique in a domain. The check ignores letter case. If a tag with the same name exists, the call returns 409.
The caller must have the admin, co-admin or editor role on the team. The team manager can always create tags. A viewer gets 403.
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 tag.
The tag name. The API removes spaces at the start and end. The name must not be empty. The maximum is 60 characters. The name must not contain < or >.
The color of the tag. Default slate. Use one of these values: slate, gray, blue, amber, red, orange, green, teal, indigo, purple, pink. Other values return 422.
Response
UUID of the new tag. Use this value in tag_ids, add_tag_ids or remove_tag_ids.
The tag name as stored.
The color key of the tag. GET /api/v1/tags gives the full color object with hex values.
UUID of the domain of the tag.
ISO-8601 time when the server made this response.
Side effects
- 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 does not have the admin, co-admin or editor role. Or the caller is not a member of the team, or the API key has no access to this domain. The plan of the team can also not include API access.
The domain or its team does not exist.
A tag with the same name exists in the domain. The check ignores letter case.
The body is not valid. For example, name is empty, has more than 60 characters or contains < or >. Or color_id is not a known color.
You sent too many requests. Read the Retry-After header to know how long to wait.