# Tags

> Create and manage ticket labels.

Source: https://tickos.dev/docs/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.

## GET /v1/tags -- List 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).

| Query param | Type | Default | Description |
|---|---|---|---|
| inbox_id | string | -- | Only tags of this inbox. |

200 OK:

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

## POST /v1/tags -- Create a tag

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.

| Field | Type | Required | Description |
|---|---|---|---|
| inbox_id | string | Yes | The inbox this tag belongs to. |
| name | string | Yes | Tag name (trimmed). Must be unique within the inbox. |
| color | string | No | Hex color code. Default: #3B82F6. |

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

## PATCH /v1/tags/{id} -- Update a tag

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 /v1/tags/{id} -- Delete a tag

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.