> ## 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.

# Update a tag

> Change the name or color of a tag using the ETag you last read in If-Match. Omitted fields keep their current values and prompt links are preserved.

Updates the supplied fields of one tag. Omitted fields keep their current values.

`Branded` and `Non-branded` are reserved system tag names, whatever the case. You cannot update one of these two system tags or rename another tag to either name.

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.

**If-Match** `string` *required*

Copy the complete `ETag` from the latest GET, including its quotes.

**brandId** `string` *required*

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

**tagId** `string` *required*

Tag identifier within this workspace.

**name** `string`

Tag name, 1 to 120 characters after trimming.

**color** `string | null`

A six-digit hex color, such as `#7B3AEE`. Set `null` to clear it.

Supply at least one of `name` or `color`.

## Response

Returns `200` with a `tag` object in the same shape as
[Get a tag](https://docs.qwairy.co/developers/endpoints/tags/get.md) and a new `ETag`. The mutation response has no
top-level `success` field. Treat versions as opaque values, not counters.

## Synthetic request and response

Read [the current tag](https://docs.qwairy.co/developers/endpoints/tags/get.md) first. This example assumes its
ETag is `"4"`.

```bash theme={null}
curl -X PATCH "https://www.qwairy.co/api/v1/brands/$BRAND_ID/tags/$TAG_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H 'If-Match: "4"' \
  -H "Content-Type: application/json" \
  -d '{"name":"Pricing and plans"}'
```

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

## Errors

| Status | Code | Cause |
| - | - | - |
| 400 | `INVALID_REQUEST` | Invalid tag fields, a system tag, or a reserved system tag name |
| 404 | `RESOURCE_NOT_FOUND` | Workspace or tag is missing or inaccessible |
| 409 | `CONFLICT` | Another tag already uses this name |
| 412 | `PRECONDITION_FAILED` | The ETag is stale or invalid |
| 428 | `PRECONDITION_REQUIRED` | `If-Match` is missing |

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.