> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/tags/openapi.json](/docs/api/tags/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Tags

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

Tag definitions, and assigning them to records one at a time or in bulk.

Contacts and companies. 9 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/tags/openapi.json](/docs/api/tags/openapi.json).

- `GET /v1/tags` - List tags (`tags.list`): [/docs/api/tags/list.md](/docs/api/tags/list.md)
- `POST /v1/tags` - Create a tag (`tags.create`): [/docs/api/tags/create.md](/docs/api/tags/create.md)
- `GET /v1/tags/{tagId}` - Get a tag (`tags.get`): [/docs/api/tags/get.md](/docs/api/tags/get.md)
- `PATCH /v1/tags/{tagId}` - Update a tag (`tags.update`): [/docs/api/tags/update.md](/docs/api/tags/update.md)
- `DELETE /v1/tags/{tagId}` - Delete a tag (`tags.delete`): [/docs/api/tags/delete.md](/docs/api/tags/delete.md)
- `POST /v1/tags/{tagId}/assignments` - Assign a tag to an entity (`tags.assign`): [/docs/api/tags/assign.md](/docs/api/tags/assign.md)
- `DELETE /v1/tags/{tagId}/assignments` - Remove a tag from an entity (`tags.unassign`): [/docs/api/tags/unassign.md](/docs/api/tags/unassign.md)
- `POST /v1/tags/{tagId}/assignments/bulk-create` - Assign a tag to many entities (`tags.bulk-assign`): [/docs/api/tags/bulk-assign.md](/docs/api/tags/bulk-assign.md)
- `POST /v1/tags/{tagId}/assignments/bulk-delete` - Remove a tag from many entities (`tags.bulk-unassign`): [/docs/api/tags/bulk-unassign.md](/docs/api/tags/bulk-unassign.md)

## List tags

`GET /v1/tags` - operationId `tags.list`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 12,000 requests a minute per API key |

Lists the workspace's tags. With `entityType` alone, the list holds the tags offered on that type: every tag
you created, plus the system and sender configuration tags whose `entityTypes` include it. With
`entityId` too, it holds the tags on that one entity.

Errors:

- `400 validation_failed`: a filter is unknown or sent in a combination its description rules out, or
`limit` or `cursor` is invalid.
- `404 not_found`: the `entityId` is not in this workspace.

Open to any workspace member.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/tags/GET/v1/tags)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer (int32) | no | Tags per page, from 1 to 200. 50 by default. Keep the same value while you page. |
| `cursor` | query | string | no | The `nextCursor` of the previous page. Omit it for the first page. |
| `entityType` | query | string | no | Lists the tags that can go on this type: `campaign`, `contact`, `mailbox`, `domain`, `reply`, `account`, `linkedin_account` or `person`. With `entityId`, lists the tags on that one entity instead. |
| `entityId` | query | integer (int64) | no | The id of one campaign, contact, mailbox, domain, account, LinkedIn account or person, to list the tags on it. Needs `entityType`, and does not work with `reply`. |
| `includeUsage` | query | boolean | no | Set to `true` to add `usage` to each tag: how many entities of each type carry it. |
| `includeEntityIds` | query | boolean | no | Set to `true` to add `entityIds` to each tag: the ids of the campaigns that carry it. Needs `entityType=campaign`. |
| `systemKey` | query | string | no | Lists only the workspace's system tag with this key, such as `champion`, the tag that marks a person as a champion Kenso watches for a job change. Kenso creates the tag the first time you ask for it. Does not work with `entityId`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a list of `Tag`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The tag's id. |
| `name` | string | The tag's name, unique in the workspace ignoring case. |
| `description` | string | A note on what the tag means. Null when the tag has none. |
| `color` | string | The tag's color, as a hex value such as `#E4D0FF` or an `rgba(...)` value. |
| `type` | string | The tag's main entity type, such as `campaign`. Read `entityTypes` for every type Kenso offers the tag on. |
| `entityTypes` | array of string | Where Kenso offers the tag: any of `campaign`, `contact`, `mailbox`, `domain`, `reply`, `account`, `linkedin_account` and `person`. A system tag or sender configuration tag can go only on these types. Any other tag can go on every type. |
| `isConfig` | boolean | True for a sender configuration tag, which groups mailboxes and domains. Like a system tag, it can go only on the types in `entityTypes`. |
| `isSystem` | boolean | True for a system tag that Kenso owns, such as a reply classification. You cannot change or delete it. |
| `systemKey` | string | The stable key of a system tag, such as `champion` or `reply_interested`. Use it to find a system tag instead of its name. Null for other tags. |
| `createdAt` | string (date-time) | When the tag was created, in UTC. |
| `updatedAt` | string (date-time) | When the tag last changed, in UTC. |
| `usage` | TagUsage | How many entities carry the tag. Present only with `includeUsage=true`. |
| `entityIds` | array of integer (int64) | The ids of the workspace's campaigns that carry the tag, in ascending order, deleted campaigns left out. Present only with `entityType=campaign` and `includeEntityIds=true`. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/tags?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": 341,
      "name": "Hot lead",
      "description": "Asked for a call or pricing",
      "color": "#FFD6A5",
      "type": "contact",
      "entityTypes": [
        "contact",
        "reply"
      ],
      "isConfig": false,
      "isSystem": false,
      "createdAt": "2026-09-23T15:02:11Z",
      "updatedAt": "2026-10-14T09:41:27Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Create a tag

`POST /v1/tags` - operationId `tags.create`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 4,800 requests a minute per API key |

Creates a tag in the workspace. Assign it with `POST /v1/tags/{tagId}/assignments`.

Errors:

- `400 validation_failed`: `name` is missing, already used or a system tag name, `color` is not a
valid color, or `entityTypes` holds an unknown type.

Requires the `workspace_settings` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/tags/POST/v1/tags)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The tag's name. Required, unique in the workspace ignoring case, and not the name of a system tag. |
| `description` | string | no | A note on what the tag means. Optional. |
| `color` | string | no | The tag's color: a hex value (`#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`) or an `rgba(r, g, b, a)` value. Omitted uses `#E4D0FF`. |
| `entityTypes` | array of string | no | Where Kenso offers the tag: any of `campaign`, `contact`, `mailbox`, `domain`, `reply`, `account`, `linkedin_account` and `person`. Omitted or empty means all of them. You cannot change it later. |

### Response 201

`data` is a `Tag`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The tag's id. |
| `name` | string | The tag's name, unique in the workspace ignoring case. |
| `description` | string | A note on what the tag means. Null when the tag has none. |
| `color` | string | The tag's color, as a hex value such as `#E4D0FF` or an `rgba(...)` value. |
| `type` | string | The tag's main entity type, such as `campaign`. Read `entityTypes` for every type Kenso offers the tag on. |
| `entityTypes` | array of string | Where Kenso offers the tag: any of `campaign`, `contact`, `mailbox`, `domain`, `reply`, `account`, `linkedin_account` and `person`. A system tag or sender configuration tag can go only on these types. Any other tag can go on every type. |
| `isConfig` | boolean | True for a sender configuration tag, which groups mailboxes and domains. Like a system tag, it can go only on the types in `entityTypes`. |
| `isSystem` | boolean | True for a system tag that Kenso owns, such as a reply classification. You cannot change or delete it. |
| `systemKey` | string | The stable key of a system tag, such as `champion` or `reply_interested`. Use it to find a system tag instead of its name. Null for other tags. |
| `createdAt` | string (date-time) | When the tag was created, in UTC. |
| `updatedAt` | string (date-time) | When the tag last changed, in UTC. |
| `usage` | TagUsage | How many entities carry the tag. Present only with `includeUsage=true`. |
| `entityIds` | array of integer (int64) | The ids of the workspace's campaigns that carry the tag, in ascending order, deleted campaigns left out. Present only with `entityType=campaign` and `includeEntityIds=true`. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/tags" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Hot lead",
  "description": "Asked for a call or pricing",
  "color": "#FFD6A5",
  "entityTypes": [
    "contact",
    "reply"
  ]
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 341,
    "name": "Hot lead",
    "description": "Asked for a call or pricing",
    "color": "#FFD6A5",
    "type": "contact",
    "entityTypes": [
      "contact",
      "reply"
    ],
    "isConfig": false,
    "isSystem": false,
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-10-14T09:41:27Z"
  }
}
```

## Get a tag

`GET /v1/tags/{tagId}` - operationId `tags.get`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 12,000 requests a minute per API key |

Returns one tag of the workspace by its id.

Errors:

- `404 not_found`: no tag of this workspace has the id, or the tag was deleted.

Open to any workspace member.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/tags/GET/v1/tags/%7BtagId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tagId` | path | integer (int64) | yes | The tag's id, as `GET /v1/tags` returns it. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `Tag`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The tag's id. |
| `name` | string | The tag's name, unique in the workspace ignoring case. |
| `description` | string | A note on what the tag means. Null when the tag has none. |
| `color` | string | The tag's color, as a hex value such as `#E4D0FF` or an `rgba(...)` value. |
| `type` | string | The tag's main entity type, such as `campaign`. Read `entityTypes` for every type Kenso offers the tag on. |
| `entityTypes` | array of string | Where Kenso offers the tag: any of `campaign`, `contact`, `mailbox`, `domain`, `reply`, `account`, `linkedin_account` and `person`. A system tag or sender configuration tag can go only on these types. Any other tag can go on every type. |
| `isConfig` | boolean | True for a sender configuration tag, which groups mailboxes and domains. Like a system tag, it can go only on the types in `entityTypes`. |
| `isSystem` | boolean | True for a system tag that Kenso owns, such as a reply classification. You cannot change or delete it. |
| `systemKey` | string | The stable key of a system tag, such as `champion` or `reply_interested`. Use it to find a system tag instead of its name. Null for other tags. |
| `createdAt` | string (date-time) | When the tag was created, in UTC. |
| `updatedAt` | string (date-time) | When the tag last changed, in UTC. |
| `usage` | TagUsage | How many entities carry the tag. Present only with `includeUsage=true`. |
| `entityIds` | array of integer (int64) | The ids of the workspace's campaigns that carry the tag, in ascending order, deleted campaigns left out. Present only with `entityType=campaign` and `includeEntityIds=true`. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/tags/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 341,
    "name": "Hot lead",
    "description": "Asked for a call or pricing",
    "color": "#FFD6A5",
    "type": "contact",
    "entityTypes": [
      "contact",
      "reply"
    ],
    "isConfig": false,
    "isSystem": false,
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-10-14T09:41:27Z"
  }
}
```

## Update a tag

`PATCH /v1/tags/{tagId}` - operationId `tags.update`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 4,800 requests a minute per API key |

Changes a tag's name, color or description. The tag stays on everything that carries it.

Send a JSON object with any of `name`, `color` and `description`. Fields you leave out keep their
value. `name` and `color` follow the rules of create and cannot be empty. A `null`
`description` clears it. `entityTypes` cannot change.

Errors:

- `400 validation_failed`: the body is not a JSON object or holds an unknown field or `entityTypes`, a
value is invalid, or the tag is a system tag.
- `404 not_found`: no tag of this workspace has the id.

Requires the `workspace_settings` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/tags/PATCH/v1/tags/%7BtagId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tagId` | path | integer (int64) | yes | The tag's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional: `object`.

### Response 200

`data` is a `Tag`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The tag's id. |
| `name` | string | The tag's name, unique in the workspace ignoring case. |
| `description` | string | A note on what the tag means. Null when the tag has none. |
| `color` | string | The tag's color, as a hex value such as `#E4D0FF` or an `rgba(...)` value. |
| `type` | string | The tag's main entity type, such as `campaign`. Read `entityTypes` for every type Kenso offers the tag on. |
| `entityTypes` | array of string | Where Kenso offers the tag: any of `campaign`, `contact`, `mailbox`, `domain`, `reply`, `account`, `linkedin_account` and `person`. A system tag or sender configuration tag can go only on these types. Any other tag can go on every type. |
| `isConfig` | boolean | True for a sender configuration tag, which groups mailboxes and domains. Like a system tag, it can go only on the types in `entityTypes`. |
| `isSystem` | boolean | True for a system tag that Kenso owns, such as a reply classification. You cannot change or delete it. |
| `systemKey` | string | The stable key of a system tag, such as `champion` or `reply_interested`. Use it to find a system tag instead of its name. Null for other tags. |
| `createdAt` | string (date-time) | When the tag was created, in UTC. |
| `updatedAt` | string (date-time) | When the tag last changed, in UTC. |
| `usage` | TagUsage | How many entities carry the tag. Present only with `includeUsage=true`. |
| `entityIds` | array of integer (int64) | The ids of the workspace's campaigns that carry the tag, in ascending order, deleted campaigns left out. Present only with `entityType=campaign` and `includeEntityIds=true`. |

### Request

```bash
curl -X PATCH "https://api.ken.so/v1/tags/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "id": 341,
    "name": "Hot lead",
    "description": "Asked for a call or pricing",
    "color": "#FFD6A5",
    "type": "contact",
    "entityTypes": [
      "contact",
      "reply"
    ],
    "isConfig": false,
    "isSystem": false,
    "createdAt": "2026-09-23T15:02:11Z",
    "updatedAt": "2026-10-14T09:41:27Z"
  }
}
```

## Delete a tag

`DELETE /v1/tags/{tagId}` - operationId `tags.delete`

| Permission | Rate limit |
| --- | --- |
| The `workspace_settings` permission | 4,800 requests a minute per API key |

Deletes a tag and removes it from the entities that carry it. A LinkedIn conversation can keep a deleted tag. You
can still remove it there with `DELETE /v1/tags/{tagId}/assignments`.

Errors:

- `400 validation_failed`: the tag is a system tag.
- `404 not_found`: no tag of this workspace has the id.

Requires the `workspace_settings` permission.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/tags/DELETE/v1/tags/%7BtagId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tagId` | path | integer (int64) | yes | The tag's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 204

### Request

```bash
curl -X DELETE "https://api.ken.so/v1/tags/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```http
HTTP/1.1 204 No Content
```

## Assign a tag to an entity

`POST /v1/tags/{tagId}/assignments` - operationId `tags.assign`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 4,800 requests a minute per API key |

Puts a tag on one campaign, contact, mailbox, domain, account, LinkedIn account, person, email reply, LinkedIn
conversation or Instagram conversation (a thread of the Instagram inbox, while the workspace has Instagram on).

Send `entityType` and the id field that type takes. Assigning a tag the entity already has changes nothing.

The caller needs edit access to the entity's page: Campaigns for a campaign or contact, Delivery for a mailbox,
domain or LinkedIn account, Accounts for an account or person, and Inbox for a reply or a conversation.

Errors:

- `400 validation_failed`: `entityType` is missing or unknown, its id field is missing, or the tag is
a system tag or sender configuration tag whose `entityTypes` do not include this entity type.
- `403 permission_denied`: the caller lacks edit access to the entity's page.
- `404 not_found`: the tag or the entity is not in this workspace, the entity was deleted, or the
`msg_` or `thr_` id belongs to another channel.

Open to any workspace member.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/tags/POST/v1/tags/%7BtagId%7D/assignments)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tagId` | path | integer (int64) | yes | The tag's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |
| `Idempotency-Key` | header | string | no | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the `Idempotent-Replayed: true` header, and Kenso does not run the action twice. The same key with a different request answers `422 idempotency_key_reused`. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get `503 service_unavailable` with `Retry-After`. Retry it with the same key. Kenso does not store a `5xx` response, so a retry after one runs the action again. It does not store a `408`, a `429` or another `4xx` that carries `Retry-After` either: retry with the same key after that time and Kenso runs the action again. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entityType` | string | yes | The entity's type: `campaign`, `contact`, `mailbox`, `domain`, `account`, `linkedin_account`, `person`, `reply`, `linkedin_conversation` or `instagram_conversation`. Required. |
| `entityId` | integer (int64) | no | The entity's id. Required for every type except `reply`, `linkedin_conversation` and `instagram_conversation`. |
| `messageId` | string | no | For `reply`: the `msg_` id of an email message, as `GET /v1/threads/{threadId}/messages` returns it. |
| `conversationId` | string | no | For `linkedin_conversation`: the `thr_` id of a LinkedIn thread, as `GET /v1/threads` returns it. For `instagram_conversation`: the `thr_` id of an Instagram thread (only that id names one). |

### Response 200

`data` is a `TagAssignment`.

| Field | Type | Description |
| --- | --- | --- |
| `tagId` | integer (int64) | The tag's id. |
| `entityType` | string | The entity's type: `campaign`, `contact`, `mailbox`, `domain`, `account`, `linkedin_account`, `person`, `reply`, `linkedin_conversation` or `instagram_conversation`. |
| `entityId` | integer (int64) | The entity's id. Null for `reply`, `linkedin_conversation` and `instagram_conversation`. |
| `messageId` | string | For `reply`, the email message id you sent. Null for other types. |
| `conversationId` | string | For `linkedin_conversation` and `instagram_conversation`, the thread id you sent. Null for other types. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/tags/812/assignments" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "entityType": "campaign",
  "entityId": 812,
  "messageId": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
  "conversationId": "thr_2bX9kq4LmR7tW3vY"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "tagId": 812,
    "entityType": "campaign",
    "entityId": 812,
    "messageId": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
    "conversationId": "string"
  }
}
```

## Remove a tag from an entity

`DELETE /v1/tags/{tagId}/assignments` - operationId `tags.unassign`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 4,800 requests a minute per API key |

Takes a tag off one entity. Send the fields of assign as query parameters, not a body. The caller needs the same
access as on assign. A deleted tag of the workspace can still come off a `reply`, a
`linkedin_conversation` or an `instagram_conversation`.

Errors:

- `400 validation_failed`: `entityType` is missing or unknown, or its id field is missing.
- `403 permission_denied`: the caller lacks edit access to the entity's page.
- `404 not_found`: the tag or the entity is not in this workspace.

Open to any workspace member.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/tags/DELETE/v1/tags/%7BtagId%7D/assignments)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tagId` | path | integer (int64) | yes | The tag's id. |
| `entityType` | query | string | no | The entity's type: `campaign`, `contact`, `mailbox`, `domain`, `account`, `linkedin_account`, `person`, `reply`, `linkedin_conversation` or `instagram_conversation`. Required. |
| `entityId` | query | integer (int64) | no | The entity's id. Required for every type except `reply`, `linkedin_conversation` and `instagram_conversation`. |
| `messageId` | query | string | no | For `reply`: the `msg_` id of an email message, as `GET /v1/threads/{threadId}/messages` returns it. |
| `conversationId` | query | string | no | For `linkedin_conversation`: the `thr_` id of a LinkedIn thread, as `GET /v1/threads` returns it. For `instagram_conversation`: the `thr_` id of an Instagram thread (only that id names one). |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |
| `Idempotency-Key` | header | string | no | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the `Idempotent-Replayed: true` header, and Kenso does not run the action twice. The same key with a different request answers `422 idempotency_key_reused`. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get `503 service_unavailable` with `Retry-After`. Retry it with the same key. Kenso does not store a `5xx` response, so a retry after one runs the action again. It does not store a `408`, a `429` or another `4xx` that carries `Retry-After` either: retry with the same key after that time and Kenso runs the action again. |

### Response 200

`data` is a `TagAssignment`.

| Field | Type | Description |
| --- | --- | --- |
| `tagId` | integer (int64) | The tag's id. |
| `entityType` | string | The entity's type: `campaign`, `contact`, `mailbox`, `domain`, `account`, `linkedin_account`, `person`, `reply`, `linkedin_conversation` or `instagram_conversation`. |
| `entityId` | integer (int64) | The entity's id. Null for `reply`, `linkedin_conversation` and `instagram_conversation`. |
| `messageId` | string | For `reply`, the email message id you sent. Null for other types. |
| `conversationId` | string | For `linkedin_conversation` and `instagram_conversation`, the thread id you sent. Null for other types. |

### Request

```bash
curl -X DELETE "https://api.ken.so/v1/tags/812/assignments" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "tagId": 812,
    "entityType": "campaign",
    "entityId": 812,
    "messageId": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
    "conversationId": "string"
  }
}
```

## Assign a tag to many entities

`POST /v1/tags/{tagId}/assignments/bulk-create` - operationId `tags.bulk-assign`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 480 requests a minute per API key |

Puts a tag on up to 1,000 entities in one call. Each item has the fields, rules and access of a single assign.
Items can mix entity types, run in request order, and fail on their own.

`results` has one entry per item, in request order, with a `status` of `assigned`,
`not_found`, `validation_failed`, `permission_denied` or `failed`. After 5 unexpected
failures in a row, Kenso marks the remaining items `failed`: retry those in a new call, with a new
`Idempotency-Key` if you send one.

Errors:

- `400 validation_failed`: `items` is empty, has more than 1,000 entries or holds a null entry. Kenso
writes nothing.
- `404 not_found`: the tag is not in this workspace.

Open to any workspace member.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/tags/POST/v1/tags/%7BtagId%7D/assignments/bulk-create)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tagId` | path | integer (int64) | yes | The tag's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |
| `Idempotency-Key` | header | string | no | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the `Idempotent-Replayed: true` header, and Kenso does not run the action twice. The same key with a different request answers `422 idempotency_key_reused`. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get `503 service_unavailable` with `Retry-After`. Retry it with the same key. Kenso does not store a `5xx` response, so a retry after one runs the action again. It does not store a `408`, a `429` or another `4xx` that carries `Retry-After` either: retry with the same key after that time and Kenso runs the action again. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of TagAssignmentRequest | no | From 1 to 1,000 items, each with the fields of a single assignment. |

### Response 200

`data` is a `TagAssignmentBulkResult`.

| Field | Type | Description |
| --- | --- | --- |
| `succeeded` | integer (int32) | How many items were assigned or removed. |
| `failed` | integer (int32) | How many items were not, for any reason. |
| `results` | array of TagAssignmentBulkItemResult | One result per item, in request order. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/tags/812/assignments/bulk-create" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "entityType": "campaign",
      "entityId": 812,
      "messageId": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
      "conversationId": "thr_2bX9kq4LmR7tW3vY"
    }
  ]
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "index": 1,
        "status": "assigned",
        "error": "string"
      }
    ]
  }
}
```

## Remove a tag from many entities

`POST /v1/tags/{tagId}/assignments/bulk-delete` - operationId `tags.bulk-unassign`

| Permission | Rate limit |
| --- | --- |
| Any workspace member except a Network member | 480 requests a minute per API key |

Takes a tag off up to 1,000 entities in one call, with the body and results of bulk assign and the rules of a
single remove. A removed item has the status `removed`. A deleted tag of the workspace can still come off
`reply`, `linkedin_conversation` and `instagram_conversation` items, and every other item then gets
`not_found`.

Errors:

- `400 validation_failed`: `items` is empty, has more than 1,000 entries or holds a null entry. Kenso
removes nothing.
- `404 not_found`: the tag is not in this workspace.

Open to any workspace member.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/tags/POST/v1/tags/%7BtagId%7D/assignments/bulk-delete)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tagId` | path | integer (int64) | yes | The tag's id. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |
| `Idempotency-Key` | header | string | no | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the `Idempotent-Replayed: true` header, and Kenso does not run the action twice. The same key with a different request answers `422 idempotency_key_reused`. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get `503 service_unavailable` with `Retry-After`. Retry it with the same key. Kenso does not store a `5xx` response, so a retry after one runs the action again. It does not store a `408`, a `429` or another `4xx` that carries `Retry-After` either: retry with the same key after that time and Kenso runs the action again. |

### Request body

`application/json`, optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of TagAssignmentRequest | no | From 1 to 1,000 items, each with the fields of a single assignment. |

### Response 200

`data` is a `TagAssignmentBulkResult`.

| Field | Type | Description |
| --- | --- | --- |
| `succeeded` | integer (int32) | How many items were assigned or removed. |
| `failed` | integer (int32) | How many items were not, for any reason. |
| `results` | array of TagAssignmentBulkItemResult | One result per item, in request order. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/tags/812/assignments/bulk-delete" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "entityType": "campaign",
      "entityId": 812,
      "messageId": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20",
      "conversationId": "thr_2bX9kq4LmR7tW3vY"
    }
  ]
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "index": 1,
        "status": "assigned",
        "error": "string"
      }
    ]
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### TagUsage

How many entities of the workspace carry a tag. Deleted entities do not count.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `campaignCount` | integer (int32) | no | Campaigns that carry the tag. |
| `contactCount` | integer (int32) | no | Contacts that carry the tag. |
| `replyCount` | integer (int32) | no | Email replies (messages) that carry the tag. |
| `linkedinConversationCount` | integer (int32) | no | LinkedIn conversations that carry the tag. |
| `inboxCount` | integer (int32) | no | Mailboxes that carry the tag. |
| `domainCount` | integer (int32) | no | Domains that carry the tag. |
| `accountCount` | integer (int32) | no | Accounts that carry the tag. |
| `linkedinAccountCount` | integer (int32) | no | LinkedIn accounts that carry the tag. |

### TagAssignmentRequest

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `entityType` | string | yes | The entity's type: `campaign`, `contact`, `mailbox`, `domain`, `account`, `linkedin_account`, `person`, `reply`, `linkedin_conversation` or `instagram_conversation`. Required. |
| `entityId` | integer (int64) | no | The entity's id. Required for every type except `reply`, `linkedin_conversation` and `instagram_conversation`. |
| `messageId` | string | no | For `reply`: the `msg_` id of an email message, as `GET /v1/threads/{threadId}/messages` returns it. |
| `conversationId` | string | no | For `linkedin_conversation`: the `thr_` id of a LinkedIn thread, as `GET /v1/threads` returns it. For `instagram_conversation`: the `thr_` id of an Instagram thread (only that id names one). |

### TagAssignmentBulkItemResult

The outcome of one item of a bulk tag assignment or removal.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `index` | integer (int32) | no | The item's position in `items`, from 0. |
| `status` | string | no | The item's outcome: `assigned` or `removed` on success, otherwise `not_found`, `validation_failed`, `permission_denied` or `failed` (retry the item). After 5 items in a row end `failed`, every remaining item is `failed` without being tried. |
| `error` | string | no | A readable explanation when the item failed. Null on success. |

All resources: [/docs.md](/docs.md).
