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

# Create one or more tags

`POST /v1/tags`

Creates tags. Send one as `tag` and get it back as `tag`, or send a list as
`tags` and get a list back. Older documentation only showed `tags`.

A label must be unique among tags of the same `entityType`, so "Competitor"
can be both a website tag and a task label. A `tagId` must be unique across
the whole account. To put website tags on a website, send their ids as
`tagIds` to [Update a website](https://developers.silktide.com/v1/governance/websites/update-website.md).

A mistake fails with status `400` and type `InvalidRequest`, and
`properties.field` names the field: a `tagId` or label already in use, a
missing `entityType`, or a `color` that is not a hex code such as `#4256D6`.
When you send `tags`, Silktide checks them all, against the account and
against each other, before it creates any. If one is refused,
`properties.index` says which, counting from `0`, and none are created.

## Request

### Body

- `tag` (object, optional): One tag to create. Send this or `tags`.
  - `tagId` (string, optional, 1 to 32 characters): An id of your own, unique in the account. Left out, Silktide makes one from the label, such as `pre-production`. Up to 32 letters, digits, hyphens or underscores; keep to lowercase, as it goes in URLs.
  - `label` (string, required, 1 to 127 characters): The tag's name, as people see it.
  - `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`.
  - `color` (string, optional, up to 32 characters): Its color, as a hex code such as `#4256D6`. Left out, Silktide picks one.
  - `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.
- `tags` (list of objects, optional): Several tags to create, in order. Send this or `tag`; when both are sent, only `tag` is created.
  - `tagId` (string, optional, 1 to 32 characters): An id of your own, unique in the account. Left out, Silktide makes one from the label, such as `pre-production`. Up to 32 letters, digits, hyphens or underscores; keep to lowercase, as it goes in URLs.
  - `label` (string, required, 1 to 127 characters): The tag's name, as people see it.
  - `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`.
  - `color` (string, optional, up to 32 characters): Its color, as a hex code such as `#4256D6`. Left out, Silktide picks one.
  - `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, optional): The tag, when you sent `tag`.
  - `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.
- `tags` (list of objects, optional): The tags, in the order sent, when you sent `tags`. Empty when `tags` was empty or neither was sent.
  - `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 |
| --- | --- | --- |
| 403 | `AccessDenied` | The API key's user cannot admin the account. |
| 400 | `InvalidRequest` | A field is missing or not valid: `entityType` missing or not one of its values, `label` empty or longer than 127 characters, `tagId` not up to 32 letters, digits, hyphens or underscores, `color` not a hex code, or `tagGroup` longer than 64 characters. Also sent when the `tagId` is already in use, a tag of the same `entityType` already has that label, two tags in `tags` clash, or `tag` is not an object. `properties.field` names the field, and for `tags` `properties.index` names the item, counting from `0`. Nothing is created. |
| 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: Create one tag for websites

```bash
curl -X POST "https://api.eu.silktide.com/v1/tags" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tag": {
    "label": "Pre-production",
    "entityType": "section"
  }
}'
```

Response:

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

## Example: Create two tags in a group

```bash
curl -X POST "https://api.eu.silktide.com/v1/tags" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tags": [
    {
      "label": "North",
      "entityType": "section",
      "tagGroup": "Region"
    },
    {
      "tagId": "south",
      "label": "South",
      "entityType": "section",
      "tagGroup": "Region",
      "color": "#3CA87C"
    }
  ]
}'
```

Response:

```json
{
  "tags": [
    {
      "tagId": "north",
      "entityType": "section",
      "label": "North",
      "color": "#EBD12C",
      "tagGroup": "Region"
    },
    {
      "tagId": "south",
      "entityType": "section",
      "label": "South",
      "color": "#3CA87C",
      "tagGroup": "Region"
    }
  ]
}
```