# Tags endpoints

Tags for people and records: list, create, rename, recolour and delete them, and add or remove them on many items at once.

Paths are relative to https://kleiobase.com/api/v1. Request and response schemas are in the OpenAPI document at https://kleiobase.com/api/v1/openapi.json.

## List tags

`GET /workspaces/{workspace_id}/tags`

By name. Not paginated: next_cursor is always null.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.

Responses:

- `200`: Tags.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `404`: The workspace does not exist or is not visible to this key's owner.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Create a tag

`POST /workspaces/{workspace_id}/tags`

A workspace has at most 200 tags. Tags are shared by people and records. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `201`: The created tag.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: a tag with this name already exists.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid name or colour, or the tag limit is reached.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Rename or recolour a tag

`PATCH /workspaces/{workspace_id}/tags/{tag_id}`

The counts in the response are 0; GET tags has them. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `tag_id` (path, required): The tag id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: The tag.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: The tag is not in this workspace.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: a tag with this name already exists.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Delete a tag

`DELETE /workspaces/{workspace_id}/tags/{tag_id}`

The tag comes off every person and record that had it. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `tag_id` (path, required): The tag id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Responses:

- `200`: Deleted.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: The tag is not in this workspace.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Add or remove tags on items

`POST /workspaces/{workspace_id}/tags/apply`

1 to 100 ids of kind, up to 50 tag ids in add and in remove. Adding a tag an item already has changes nothing. All or nothing: every item must be in this workspace and not in Trash, and every tag must be in this workspace. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: Applied.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: One of the items or tags is not in this workspace (or the item is in Trash).
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body, neither add nor remove, or the same tag in both.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

Canonical: https://kleiobase.com/developers/docs/reference/tags