> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a tag

> Create a reusable workspace tag with an optional color. The tag is not attached to any prompt until you update a prompt or run a bulk prompt update.

Creates a tag without attaching it to any prompt. To apply it, [update a prompt](https://docs.qwairy.co/developers/endpoints/prompts/update.md)
or use [bulk prompt updates](https://docs.qwairy.co/developers/endpoints/prompts/bulk.md).

`Branded` and `Non-branded` are reserved system tag names, whatever the case. In a workspace created from v1.21, Qwairy creates these two tags itself and sets one on each prompt from its text. In every workspace, a request that uses either name as `name` is refused.

Requires an active Business, Agency Business or Enterprise plan. Use an API token with write access enabled. See [Writing data](https://docs.qwairy.co/developers/writing-data.md) for
idempotency, conditional requests and error handling.

**Authorization** `string` *required*

Bearer token for your team.

**Idempotency-Key** `string` *required*

Unique key for this operation. Completed responses replay for 24 hours.

**brandId** `string` *required*

Workspace identifier. The workspace must belong to the token's team.

**name** `string` *required*

Tag name, 1 to 120 characters after trimming.

**color** `string | null`

Optional six-digit hex color, such as `#7B3AEE`. Defaults to `null`.

## Response

Returns `201` with `Location`, `ETag` and a `tag` object containing
`id`, `name`, nullable `color`, `version`, `createdAt` and `updatedAt`.

## Synthetic request and response

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/tags" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: tag-pricing-001" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pricing","color":"#7B3AEE"}'
```

```json theme={null}
{
  "tag": {
    "id": "22222222-0000-4000-8000-000000000000",
    "name": "Pricing",
    "color": "#7B3AEE",
    "version": 0,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z"
  }
}
```

## Errors

Invalid fields, or a reserved system tag name (`Branded` or `Non-branded`, whatever the case), return `400 INVALID_REQUEST`; a missing workspace returns
`404 RESOURCE_NOT_FOUND`; a duplicate name returns `409 CONFLICT`.

See [Error codes](https://docs.qwairy.co/developers/errors.md) for authentication, plan, idempotency
and server errors. On `429`, honor `Retry-After`; writes can return
`503 SERVICE_UNAVAILABLE` if the write limiter is unavailable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.