# Tags

A tag is a colored label on tickets, such as bug. Workspace tags work on every ticket and belong to owners and admins; team tags work only on their team's tickets, and the team's members manage them too.

## The Tag object

A colored label on tickets. Workspace tags work on every ticket; team tags only on their team's tickets.

### Attributes

- `id` (string, required): Unique ID of the tag.
- `name` (string, required): The tag's name, such as bug.
- `color` (string, one of: `gray`, `red`, `orange`, `amber`, `green`, `teal`, `cobalt`, `iris`, `pink`, required): The tag's color.
- `team` (nullable object, required): The team a team tag belongs to; null for a workspace tag.
  - `id` (string, required): Unique ID of the team.
  - `key` (string, required): The team's key, such as WEB.

### Example

```json
{
  "id": "Tg3FtR7nWq2K",
  "name": "feature",
  "color": "cobalt",
  "team": null
}
```

## List tags

`GET /v1/workspaces/{slug}/tags`

Returns workspace tags and the team tags of every team the caller sees or, with `team`, workspace tags and that team's tags.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `team` (string, in query): A team's key, such as WEB, for the tags that team's tickets can use.

### Returns

Returns an object with these fields. The status is 200.

- `tags` (array of objects, required): The tags, sorted by name. See [the Tag object](https://docs.qa.clankership.net/api/tags/object.md).
  - `id` (string, required): Unique ID of the tag.
  - `name` (string, required): The tag's name, such as bug.
  - `color` (string, one of: `gray`, `red`, `orange`, `amber`, `green`, `teal`, `cobalt`, `iris`, `pink`, required): The tag's color.
  - `team` (nullable object, required): The team a team tag belongs to; null for a workspace tag.
    - `id` (string, required): Unique ID of the team.
    - `key` (string, required): The team's key, such as WEB.

### Request

```bash
curl https://api.qa.clankership.net/v1/workspaces/{slug}/tags \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ]
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Create a tag

`POST /v1/workspaces/{slug}/tags`

Owners and admins create workspace tags, and a team's members also create its team tags; viewers cannot. A workspace tag's name must differ from every tag's, and a team tag's from the workspace tags and the team's own.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `name` (string, required): The tag's name, up to 40 characters, such as bug.
- `color` (string, one of: `gray`, `red`, `orange`, `amber`, `green`, `teal`, `cobalt`, `iris`, `pink`, required): The tag's color.
- `team` (nullable string): The key of the team a team tag belongs to, such as WEB. Leave it out for a workspace tag.

### Returns

Returns the [Tag](https://docs.qa.clankership.net/api/tags/object.md) object. The status is 201.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/tags \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search",
    "color": "teal",
    "team": "WEB"
  }'
```

### Response

```json
{
  "id": "Tg3FtR7nWq2K",
  "name": "feature",
  "color": "cobalt",
  "team": null
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Update a tag

`PATCH /v1/workspaces/{slug}/tags/{tag}`

Renames or recolors a tag; only the fields sent change. Saved view filters follow a new name. The people who can create the tag can change it.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `tag` (string, in path, required): The tag's ID.
- `name` (string): The tag's name, up to 40 characters.
- `color` (string, one of: `gray`, `red`, `orange`, `amber`, `green`, `teal`, `cobalt`, `iris`, `pink`): The tag's color.

### Returns

Returns the [Tag](https://docs.qa.clankership.net/api/tags/object.md) object. The status is 200.

### Request

```bash
curl -X PATCH https://api.qa.clankership.net/v1/workspaces/{slug}/tags/{tag} \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "iris"
  }'
```

### Response

```json
{
  "id": "Tg3FtR7nWq2K",
  "name": "feature",
  "color": "cobalt",
  "team": null
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Delete a tag

`DELETE /v1/workspaces/{slug}/tags/{tag}`

Takes the tag off every ticket and out of saved view filters. The people who can create the tag can delete it.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `tag` (string, in path, required): The tag's ID.

### Returns

Returns no content. The status is 204.

### Request

```bash
curl -X DELETE https://api.qa.clankership.net/v1/workspaces/{slug}/tags/{tag} \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.