Tags tags
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through tags_read and changes through tags_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: assign, bulk-assign, bulk-unassign, create, delete, get, list, unassign, update
assign
Write. POST https://api.ken.so/v1/tags/{tagId}/assignments
Path: tagId
Body (json): conversationId string, entityId integer, entityType string, messageId string
Assign a tag to one entity. Public. Needs workspace membership plus the entity type's page edit access. reply uses message_id.
POST /api/v1/tags/{tagId}/assignments. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
entity_type campaign, contact, mailbox, domain, account, linkedin_account, or person uses entity_id.
mailbox, domain, and linkedin_account need Delivery edit.
reply uses message_id: the msg_ id of an email message, from
threads(operation="list-messages", thread_id=...). linkedin_conversation uses
conversation_id: the thr_ id of a LinkedIn thread, from
threads(operation="list", channel="linkedin"). Raw stored ids still work. An id of
the other channel (a LinkedIn msg_ for reply, an email thr_ for linkedin_conversation)
is a 404. instagram_conversation uses conversation_id: the thr_ id of an Instagram
thread, from threads(operation="list", channel="instagram"); only that id works, and
a chat the workspace cannot see (or any while Instagram is off) is a 404. To make a person a
champion, assign the Champion tag (list with system_key champion) with entity_type person.
Any tag that is not a system tag can go on any entity type. Assigning a tag
the entity already has succeeds. An entity outside the workspace is a 404.
bulk-assign
Write. POST https://api.ken.so/v1/tags/{tagId}/assignments/bulk-create
Path: tagId
Body (json): items array
Assign one tag to up to 1,000 entities in one call. Public. Needs workspace membership plus the entity type's page edit access. Prefer this over api_tags_assign in a loop.
POST /api/v1/tags/{tagId}/assignments/bulk-create. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
items: 1 to 1,000 objects shaped like the tags(operation="assign") target:
{ "entityType": ..., "entityId" | "messageId" | "conversationId": ... }.
campaign, contact, mailbox, domain, account, linkedin_account, and person use entityId. reply uses messageId,
an email message's msg_ id from threads(operation="list-messages", thread_id=...). linkedin_conversation
uses conversationId, a LinkedIn thread's thr_ id from threads(operation="list", channel="linkedin").
Raw stored ids still work. instagram_conversation uses conversationId, an Instagram thread's thr_ id
from threads(operation="list", channel="instagram"). snake_case names work too.
Each item reports its own result in data.results (by index) with status
assigned, not_found, validation_failed, or failed. data.succeeded and
data.failed count them. Once sent, one failing item does not stop the others.
A malformed item (missing id, unknown entityType) fails the whole call before
sending, and the error names it as items[index]. An empty or oversized items
list is a 400, and a tag outside the workspace is a 404.
bulk-unassign
Write. POST https://api.ken.so/v1/tags/{tagId}/assignments/bulk-delete
Path: tagId
Body (json): items array
Remove one tag from up to 1,000 entities in one call. Public. Needs workspace membership plus the entity type's page edit access. Same items as api_tags_bulk_assign.
POST /api/v1/tags/{tagId}/assignments/bulk-delete. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
items: 1 to 1,000 objects, each { "entityType": ..., "entityId" | "messageId" |
"conversationId": ... }, the same shape as tags(operation="assign"): messageId is a msg_
id from threads(operation="list-messages", thread_id=...) and conversationId a thr_ id
from threads(operation="list", channel="linkedin"). Prefer this over
tags(operation="unassign") in a loop.
Each item reports its own result in data.results (by index) with status
removed, not_found, validation_failed, or failed. data.succeeded and
data.failed count them. Once sent, one failing item does not stop the others.
A malformed item fails the whole call before sending, and the error names it
as items[index].
create
Write. POST https://api.ken.so/v1/tags
Body (json): color string, description string, entityTypes array, name string
Create a tag definition. Returns 201. Public. Needs the workspace settings permission. Omit entity_types for one tag usable everywhere.
POST /api/v1/tags. Public. Sends Ken-Version 1.1. client_id is sent as X-Ken-Workspace-Id. entity_types: campaign, contact, mailbox, domain, reply, account, linkedin_account, person. Omitted or empty means all of them. Only Classic lists the tag under these alone; the API lists and assigns a user tag on any entity type. A name already used in the workspace is a 400. color is hex or rgba(). Omitted color uses the API default.
delete
Write. DELETE https://api.ken.so/v1/tags/{tagId}
Path: tagId
Delete a tag definition and its assignments. Returns 204. Public. Needs the workspace settings permission.
DELETE /api/v1/tags/{tagId}. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Soft-deletes the definition.
get
Read. GET https://api.ken.so/v1/tags/{tagId}
Path: tagId
Get one tag definition. Public. Open to any workspace member.
GET /api/v1/tags/{tagId}. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
list
Read. GET https://api.ken.so/v1/tags
Query: cursor string, entityId integer, entityType string, includeEntityIds boolean, includeUsage boolean, limit integer, systemKey string
List tag definitions in the current workspace. Public. entity_type lists the tags that can go on that type. entity_id lists tags on that entity. include_usage=true adds per-tag assignment counts. include_entity_ids=true adds the campaigns on each tag.
GET /api/v1/tags. Public. Sends Ken-Version 1.1. client_id is sent as X-Ken-Workspace-Id. Open to any workspace member. entity_type is campaign, contact, mailbox, domain, reply, account, linkedin_account, or person. entity_id with campaign, contact, mailbox, domain, account, linkedin_account, or person lists the tags on it. system_key returns the workspace's one system tag with that key, created on first use: system_key champion is the Champion tag, the person tag that makes a person a champion. It cannot be combined with entity_id. include_usage=true adds usage to each tag: campaignCount, contactCount, replyCount (email messages), linkedinConversationCount, inboxCount, domainCount, accountCount, linkedinAccountCount. Counts are live assignments in the workspace; deleted targets do not count. Without it usage is absent. include_entity_ids=true needs entity_type campaign: it adds entityIds to each tag, the ids (ascending) of the workspace's live campaigns carrying it, so one call answers which tags every campaign has. Without it entityIds is absent.
unassign
Write. DELETE https://api.ken.so/v1/tags/{tagId}/assignments
Path: tagId
Query: conversationId string, entityId integer, entityType string, messageId string
Remove one tag assignment. Public. Needs workspace membership plus the entity type's page edit access. Same target fields as assign.
DELETE /api/v1/tags/{tagId}/assignments. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
reply uses message_id, the msg_ id from threads(operation="list-messages", thread_id=...).
linkedin_conversation uses conversation_id, the thr_ id from
threads(operation="list", channel="linkedin"). Raw stored ids still work.
instagram_conversation uses conversation_id, the thr_ id from
threads(operation="list", channel="instagram").
update
Write. PATCH https://api.ken.so/v1/tags/{tagId}
Path: tagId
Update a tag definition. Absent fields stay unchanged. Public. Needs the workspace settings permission. null description clears it.
PATCH /api/v1/tags/{tagId}. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id.
entityTypes cannot be changed.