Tags

Tags are colored labels that you can assign to tickets within an inbox. Each tag belongs to a specific inbox, and tag names are unique per inbox (case-sensitive). A tag object has id, name, color, inbox_id and created_at.

List tagsGET/v1/tags

Permission: read. Returns all tags across the inboxes of the account, sorted by name. This endpoint is not paginated: it returns every tag plus a count. Pass inbox_id to list only the tags of one inbox (404 if the inbox is not in your account).

01{
02  "data": [
03    { "id": "tag_xxxxxxxx", "name": "billing", "color": "#3B82F6", "inbox_id": "inb_xxxxxxxx", "created_at": "2026-10-01T12:00:00.000Z" }
04  ],
05  "count": 1
06}

Create a tagPOST/v1/tags

Permission: write. Returns 201 with { tag }. Returns 400 if inbox_id or name is missing, 404 if the inbox is not in your account, and 409 if the inbox already has a tag with that name.

01curl -X POST https://api.tickos.dev/v1/tags \
02  -H 'Authorization: Bearer sk_your_api_key' \
03  -H 'Content-Type: application/json' \
04  -d '{ "inbox_id": "inb_xxxxxxxx", "name": "billing", "color": "#16A34A" }'

Update a tagPATCH/v1/tags/{id}

Permission: write. Accepts name and/or color (at least one required, else 400). The tag stays in its inbox. Returns { tag } including updated_at. Returns 404 if the tag is not in your account and 409 if another tag in the same inbox already has the new name.

Delete a tagDELETE/v1/tags/{id}

Permission: write. Permanently deletes the tag, so it no longer appears on any ticket. Returns { "success": true }, or 404 if the tag is not in your account.