<!-- https://developers.silktide.com/v1/platform/tags/update-tag | Platform / Tags -->

# Update a tag

`PUT /v1/tags/{tagId}`

Changes a tag's label, color or group. Wherever the tag is used, it shows the
change at once.

Send the changes inside a `tag` object. A body without one fails with status
`400`. `tagId` and `entityType` are ignored if you send them: a tag keeps its
id and type for good, so a renamed tag keeps its old id.

Like [Create a tag](https://developers.silktide.com/v1/platform/tags/create-tag.md), it refuses a label that
another tag of the same type already has. Only the fields you change are
checked, so a tag saved before a rule existed can be resaved as it is.

## Request

### Path parameters

- `tagId` (string, required, 1 to 32 characters): The tag.

### Body

- `tag` (object, required): What to change. Leave out what should keep its value. `tagId` and `entityType` cannot change.
  - `label` (string, optional, 1 to 127 characters): The tag's name, as people see it.
  - `color` (string, optional, up to 32 characters): Its color, as a hex code such as `#4256D6`, or empty for none.
  - `tagGroup` (string, optional, up to 64 characters): A group to show it in, such as `Region`. Tags with the same group are shown together. Empty for none.

## Response

Status `200`.

- `tag` (object, required): The tag, as it is now.
  - `tagId` (string, required, 1 to 32 characters): The tag's id. Use it in `tagIds`, and in the path of Update a tag and Delete a tag.
  - `entityType` (string, required): What the tag is for: `section` for websites and their sections, `document` for documents, `task` for tasks. Each type has its own tags. One of: `section`, `document`, `task`.
  - `label` (string, required): The tag's name, as people see it.
  - `color` (string, required): Its color, as a hex code such as `#ED4B4B`.
  - `tagGroup` (string, required): The group it is shown in, such as `Region`. Empty when it has none.

## Errors

| Status | Type | When |
| --- | --- | --- |
| 404 | `ModelNotFound` | No tag with that id exists in the account. |
| 403 | `AccessDenied` | The API key's user cannot admin the account. |
| 400 | `InvalidRequest` | The body has no `tag` object, or a changed field is not valid: `label` empty, longer than 127 characters or already used by another tag of the same `entityType`, `color` not a hex code, or `tagGroup` longer than 64 characters. `properties.field` names the field. |
| 401 | `NotLoggedIn` | No API key was sent, or it is not a key for this region. |
| 429 | `TooManyRequests` | Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats. |
| 503 | - | Silktide is busy. Retry after the number of seconds in the `Retry-After` header. |

## Access

- Permission: Can admin this account
- Plan feature: none
- Edition: Silktide 4 and Silktide 5
- Cost: free
- Stability: stable, since 1.0.0

## Example: Rename a tag and give it a group

```bash
curl -X PUT "https://api.eu.silktide.com/v1/tags/pre-production" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tag": {
    "label": "Staging",
    "tagGroup": "Environment"
  }
}'
```

Response:

```json
{
  "tag": {
    "tagId": "pre-production",
    "entityType": "section",
    "label": "Staging",
    "color": "#D08736",
    "tagGroup": "Environment"
  }
}
```