Account account
The caller's own account. My alerts (which events notify me by email, in app, Slack or Teams): get-notification-preferences, with event to read only those events (event="interested" for interested replies), then update-notification-preferences.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through account_read and changes through account_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: append, cancel-deletion, delete-avatar, audit-events-export, get, slack-connection-get, teams-connection-get, get-notification-preferences, get-preferences, list, mcp-calls-list, mcp-clients-list, slack-channels-list, list-notifications, replace-avatar, request-deletion, update, update-notification-preferences, update-preferences
append
Write. POST https://api.ken.so/v1/build-sessions/{buildSessionId}/tool-calls
Path: buildSessionId
Body (json): toolCalls array
Append tool-call records for a build session. Internal. Requires Campaigns edit access. Returns 204.
POST /api/v1/build-sessions/{buildSessionId}/tool-calls. Internal.
Sends Ken-Version 1.1. Requires Campaigns edit access. Returns 204. Each record needs
toolCallId, toolName, status, and startedAt. A session outside the
workspace is not_found before the write.
cancel-deletion
Write. DELETE https://api.ken.so/v1/me/deletion-request
Cancel a pending account deletion. Empty success means the pending deletion was canceled.
DELETE /api/v1/me/deletion-request with Ken-Version 1.1. Internal exposure. The backend returns 204 with an empty body. It keeps open every workspace that was closing with the account. Refused with 409 conflict once the deletion is being finalized or a closing workspace is due (its plan may already be cancelled).
delete-avatar
Write. DELETE https://api.ken.so/v1/me/avatar
Remove the caller's avatar. Empty success means the avatar was removed.
DELETE /api/v1/me/avatar with Ken-Version 1.1. Internal exposure. The backend returns 204 with an empty body, which this client surfaces as success true.
audit-events-export
Write. POST https://api.ken.so/v1/audit-events/export
Body (json): occurredAfter date-time, occurredBefore date-time
Export the workspace's audit log lines (operation action) as CSV text, newest first. Internal. Requires the members permission. Writes the line "Exported the audit log as CSV".
POST /api/v1/audit-events/export. Internal. Sends Ken-Version 1.1.
Requires the members permission. The workspace is X-Ken-Workspace-Id. occurred_after
(inclusive) and occurred_before (exclusive) are optional ISO-8601 instants
with Z or an offset; without them the file holds every action line. Lines
written after the export starts are not in it. Returns {format: csv,
rowCount, csv}. The header is
occurred_at,actor,actor_kind,action,summary,resource_type,resource_id.
occurred_at is ISO-8601 UTC with Z; actor is the name the list shows
(Ken for Ken's own work); actor_kind is user, agent, api_key, system or
workflow; resource_type is the snake_case entity type. More than 50,000
lines in the range is validation_failed with detail too_many_rows: narrow
the range. Up to 5,000 rows come back here; past that the CSV is cut,
truncated is true, and the full file is the Settings > Security download in
the Kenso app. Each export writes the line "Exported the audit log as CSV"
(action audit_log.exported) to the same log.
get
Read. GET https://api.ken.so/v1/me
Return the authenticated caller, with their time zone and local time. Sends Ken-Version 1.1. client_id selects the workspace role.
GET /api/v1/me. Public. Replaces GET /v1/me/context, GET /v1/users/me, and GET /v1/workspaces/me. When client_id is set, or a workspace is already pinned, the response role is the caller's role in that workspace. A super admin stays super_admin. The id is sent as X-Ken-Workspace-Id, never as clientId. Omit client_id when no workspace is selected. data.features is the sorted list of feature flag keys that are on for the caller in that workspace (always present, empty when none). With no client_id and no pinned workspace, the caller's only workspace is used; with several, workspace overrides do not apply. Manage flags with admin_misc(operation="feature_flags") (staff). data.hasPaidPlan says whether that same workspace is on a paid plan: true or false, null for a super admin, with no workspace, or when the plan could not be read. data.timeZone is the caller's app time zone (IANA, such as Europe/Amsterdam; absent when they set none), the zone Kenso uses for their Today, Calls and sidebar counts. Notifications use the zone saved with their daily brief first, then this one. data.localTime is the current time there (ISO 8601 with its UTC offset, such as 2026-10-25T14:05+01:00; added by this server, null without a time zone). Use them for "today", "tomorrow" and every time you show the caller. data.language is the caller's language, a BCP 47 tag such as fr or fr-FR; absent when they set none, which means en. data.instagramUrl, data.xUrl, data.youtubeUrl and data.githubUrl are the caller's own profile links (absent when unset). Each data.workspaces[] item may carry socialPosts: whether the caller's own social posts feed that workspace. mode is the caller's choice (auto, on or off), on says whether they feed it now, and reason is client_seat, kenso_staff (Kenso staff's posts feed only Kenso's own workspace), chosen_on, chosen_off, email_domain_match, only_workspace or no_match. The person changes it in the Kenso app (Settings, Profile); no tool changes it. Response envelope: success plus data (canonical resource).
slack-connection-get
Read. GET https://api.ken.so/v1/integrations/slack/connection
Read the caller's Slack connection in the workspace. data.available is false until the Kenso Slack app is set up. Not for the Client role.
GET /api/v1/integrations/slack/connection. Internal. Sends Ken-Version 1.1. Fields: available, connected, teamName, channelId, channelName, connectedAt, approveFromSlack, dailyBriefInSlack. connected means the caller is connected in this workspace and the Kenso bot is still installed in their Slack. not_found while the notifications feature is off for the workspace. Connecting and disconnecting happen in the Kenso app under Settings > Notifications; there is no tool for them.
teams-connection-get
Read. GET https://api.ken.so/v1/integrations/teams/connection
Read the caller's Microsoft Teams connection in the workspace. data.available is false until the Kenso Teams bot is set up. Not for the Client role.
GET /api/v1/integrations/teams/connection. Internal. Sends Ken-Version 1.1. Fields: available, connected, teamsUserName, teamsUserPrincipalName, destination (personal or channel), channelName, teamName, connectedAt, approveFromTeams, dailyBriefInTeams, chatUrl. connected means the caller linked their Teams account in this workspace. approveFromTeams is reserved: approving from Teams is not available yet, so it is always false for now and has no effect. not_found while the notifications feature is off for the workspace. Connecting and disconnecting happen in the Kenso app under Settings > Integrations > Microsoft Teams; there is no tool for them.
get-notification-preferences
Read. GET https://api.ken.so/v1/me/notification-preferences
Return the caller's own notification preferences (my alerts). data.preferences lists eventKey, isEnabled (Email) and channels; data.destinations says if Slack is connected. event keeps only the events about it: event="interested" for interested replies.
GET /api/v1/me/notification-preferences with Ken-Version 1.1.
Internal exposure. Response envelope: success plus data. It is always the
caller's own grid; a teammate's preferences are not readable here.
event: every word must appear, ignoring case, in the event's eventKey
(underscores read as spaces), displayName or description, so
event="interested reply" keeps positive_reply ("Email alert when a
campaign lead is classified as interested") and coaching_reply_waiting.
dailyBrief and destinations stay whole. An empty preferences list means
no event matched: read again without event to see every event.
data.preferences: one row per event with eventKey, displayName,
description, isEnabled (the Email toggle), isDefaultEnabled,
channels {inApp, email, slack, teams} (saved choice, else the event
default), defaultChannels (same shape), surface (classic or
accounts) and isLocked. Accounts events are listed when the
notifications feature is on for the workspace or for any other
workspace the caller is a member of, since those workspaces email the
caller; their In app, Slack and Teams change only where the feature
is on. Always-on system
events (billing, onboarding, domain import, access requests) are
listed only for a super admin, with isLocked true; everyone else
gets them on their defaults and cannot change them.
data.dailyBrief: time (HH:mm), timeZone (IANA) and timeZoneSource
(user, calendar or default). data.destinations: email, slack
{connected, channelName} and teams {connected, destination,
channelName, teamName} for the workspace. client_id is sent as
X-Ken-Workspace-Id and picks the workspace.
get-preferences
Read. GET https://api.ken.so/v1/me/preferences
Return the caller's synced app preferences. showShortcutHints, advanceAfterDone, sharePageContext, theme, and whatsNew.
GET /api/v1/me/preferences with Ken-Version 1.1. Internal exposure. One set per user, the same in every workspace and on every device. data.showShortcutHints, data.advanceAfterDone and data.sharePageContext are booleans that read true until the user changes them. data.theme is light, dark, or system, and is omitted when the user never chose one. data.whatsNew is the app's What's new read state: since (the user's sign-up time, UTC) and done (the ids of the updates, tips, pop-outs and walkthroughs the user has seen or dismissed, oldest first, at most 500). The app writes it; no MCP operation changes it. Response envelope: success plus data.
list
Read. GET https://api.ken.so/v1/audit-events
Query: action string, cursor string, limit integer, occurredAfter date-time, occurredBefore date-time, operation string, resourceId string, resourceType string
List one workspace's audit events, newest first. Internal. Requires the members permission. There is no totalCount. operations="action" lists the readable lines (who did what) that Settings > Security shows.
GET /api/v1/audit-events. Internal. Sends Ken-Version 1.1.
Requires the members permission. The workspace is X-Ken-Workspace-Id. Pages are newest
first. limit is 1 to 200 and cursor continues that order. Omit limit for
the server default. There is no totalCount. Optional resourceType and
resourceId are supplied together. resourceType campaign includes the same
child roots as the campaign audit log: email_sequence, audience,
prompt_library, and ai_flow_model_configuration. Each event's operation is
insert, update, delete, or action; operations filters on it (one or
several, comma-separated, any of them matches; sent as the operation query
parameter). insert, update and delete rows are entity changes with changes
JSON. action rows are the readable lines: they carry action (a token such
as data_retention.updated or api_key.created) and summary (the line
without the actor, such as "Set data retention to 12 months"); actorName
says who ("Jordan Mills", "Jordan Mills via Claude Code", or Ken for Ken's
own work). action filters by token (comma-separated, at most 50, any of
them matches) and lists action rows only.
occurred_after (inclusive) and occurred_before (exclusive) are ISO-8601
instants with Z or an offset. Entity type names are lowercase snake_case.
A campaign outside the workspace is not_found before the list. The
cross-tenant global log stays on account(operation="audit_log_query").
Legacy audit-log tools stay.
mcp-calls-list
Read. GET https://api.ken.so/v1/mcp/calls
Query: cursor string, limit integer
List the MCP tool calls made in one workspace, newest first. Internal. Each row names the tool, operation, client and member.
GET /api/v1/mcp/calls. Internal. Sends Ken-Version 1.1. The workspace is
X-Ken-Workspace-Id (client_id). Rows are kept 30 days, newest first.
limit is 1 to 200 (server default 50); cursor continues the same order from
pagination.nextCursor while pagination.hasMore is true.
Each row: id, occurredAt, tool, operation (when the tool has one), name,
client {key, name} (the MCP client, e.g. claude-code / Claude Code; absent
when unknown), isKenAgent (true for Kenso's own agents), user {id, name}
(absent when the member is unknown), args (a one-line scalar summary of the
arguments; never bodies, prompts or secrets; on another member's row it is
absent unless the caller has the Manage members permission), ok, errorCode
(when ok is false, e.g. not_found), durationMs. isKenAgent is true only for
calls made with a token Kenso's own app minted; a client that merely names
itself a Kenso agent is recorded as an outside client.
Before the backend ships the route this returns success false with
error.code not_available.
mcp-clients-list
Read. GET https://api.ken.so/v1/mcp/clients
List the outside MCP clients that called this workspace in the last 30 days. Internal. Kenso's own agents are not listed.
GET /api/v1/mcp/clients. Internal. Sends Ken-Version 1.1. The workspace is X-Ken-Workspace-Id (client_id). Each row: key (the client's raw name, e.g. claude-code), name (its display name, e.g. Claude Code), lastCallAt, callCount. Only clients with calls in the last 30 days, and never Kenso's own agents (isKenAgent rows in mcp-calls-list). Before the backend ships the route this returns success false with error.code not_available.
slack-channels-list
Read. GET https://api.ken.so/v1/integrations/slack/channels
Query: cursor string, limit integer
List the Slack channels a workflow step can post to or ask in. The caller's connected Slack team. Not for the Client role.
GET /api/v1/integrations/slack/channels. Internal. Sends Ken-Version 1.1. Items: id, name, isPrivate, teamId. The channels the caller is in: public ones, and private ones Kenso was invited to as well; archived ones are left out. limit 1 to 200 (default 50). Slack can return fewer items than limit with more to come: pass pagination.nextCursor back unchanged. conflict slack_not_connected until the caller connects Slack in the Kenso app (Settings > Notifications); not_found while the notifications feature is off.
list-notifications
Read. GET https://api.ken.so/v1/me/notifications
Query: cursor string, limit integer, status string
List the caller's In app notifications in a workspace. data.unreadCount and one page of data.items: unread only, or read and unread with status="all". Read-only.
GET /api/v1/me/notifications with Ken-Version 1.1. Internal exposure. client_id is sent as X-Ken-Workspace-Id. status is "unread" (the backend default: unread items only) or "all" (read and unread; read items are kept for 90 days after they were marked read). limit is 1..50 (backend default 20). cursor is pagination.nextCursor from the previous page; pagination.hasMore says whether an older page exists. data.unreadCount counts every unread item. data.items is newest first: id (ntf_ plus a number), eventKey, title, body, linkPath, createdAt, isRead, and seenAt once read. 404 while the notifications feature is off for the workspace. Reading does not mark anything seen; only the Kenso app does that.
replace-avatar
Write. PUT https://api.ken.so/v1/me/avatar
Replace the caller's avatar from an image. PNG, JPEG, or WebP, under 10 MB. Multipart field name is file.
PUT /api/v1/me/avatar with Ken-Version 1.1. Internal exposure. file_content_base64 is the image bytes in base64 and file_name its name (.png, .jpg, .jpeg, or .webp), under 10 MB. The hosted MCP refuses file_path, because it cannot read your machine; off the hosted MCP, file_path opens only a file inside the MCP export directory. The request is multipart with field name file. The response is the updated caller resource.
request-deletion
Write. POST https://api.ken.so/v1/me/deletion-request
Body (json): newAdmins array
Schedule deletion of the caller's account in 14 days. Run with preview=true first: it shows what happens to each workspace and changes nothing.
preview=true: GET /api/v1/me/deletion-request with Ken-Version 1.1. It
writes nothing. data.status is pending (with data.dueAt) or none, and
data.workspaces lists every workspace the caller is in with its outcome:
closes (the caller is its admin and only member, not counting Ken staff
and pending invitations: it is deleted on the due date and its own paid
plan is cancelled), needs_new_admin (the caller is its last admin and
others are there; members lists who can be chosen, longest-standing
first), blocked (the caller runs it alone but it shares a white-label
plan, so it cannot close: another admin must be added first) or stays.
Otherwise POST /api/v1/me/deletion-request with Ken-Version 1.1.
Internal exposure. Idempotent while a deletion is already pending.
data.dueAt is the scheduled time and data.workspaces the outcomes.
new_admins names the new admin of each needs_new_admin workspace: a
list of {workspace_id, user_id} (workspaceId and userId are aliases),
one per workspace. That member becomes Admin now and stays Admin if the
deletion is cancelled. Without a choice for each such workspace the
request is refused with 409 conflict and one error.details entry per
workspace (code last_admin, workspaceId, workspaceName); a blocked
workspace refuses it too (code shares_plan). A choice that
is not an active member of that workspace is 404 not_found with an
error.details entry (code new_admin_not_found, field newAdmins[i],
workspaceId), and nothing changes. A closes workspace
needs no choice. Confirm both lists with the person before calling.
update
Write. PATCH https://api.ken.so/v1/me
Body (json): firstName string, githubUrl string, instagramUrl string, jobTitle string, language string, lastName string, linkedinUrl string, timeZone string, xUrl string, youtubeUrl string
Update the caller's profile: name, job title, time zone, language, social links. Omit a field to leave it unchanged. Empty string clears it.
PATCH /api/v1/me with Ken-Version 1.1. Internal exposure: workspace admins and staff. The backend still allows every workspace role to edit their own profile; a restricted caller is hidden from this tool. Each field is optional. Absent is unchanged. Null is not representable here; pass an empty string to clear a field. Values are trimmed. - first_name, last_name: at most 100 characters each. - job_title: at most 200 characters. - time_zone: an IANA id such as America/New_York or Europe/London. Windows ids (Eastern Standard Time) and offsets are refused. It is stored for display only and does not change any send schedule. - language: BCP 47 tag such as fr or fr-FR (fr-fr is stored as fr-FR); an empty string clears it, which stores null; null means en. The caller's reading language; the app itself stays English. - linkedin_url, instagram_url, x_url, youtube_url, github_url: the caller's own profiles. Kenso stores the last four in one canonical form (twitter.com becomes https://x.com/<handle>); a link on another site, or a post, video or search page instead of a profile, is 400 validation_failed with detail code wrong_platform, not_a_profile or invalid_url. linkedin_url is stored canonical when it is a LinkedIn profile (/in/...), else as sent. Saving linkedin_url may enqueue a best-effort avatar derivation when no photo exists. An invalid value fails the whole request with 400 validation_failed and one error.details entry per field (firstName, lastName, jobTitle, timeZone, language, instagramUrl, xUrl, youtubeUrl, githubUrl). The returned caller resource carries data.jobTitle, data.timeZone and data.language (omitted when unset; no language means en) and data.features (enabled feature flag keys, sorted, same rule as account(operation="get")). Response envelope: success plus data (the caller resource).
update-notification-preferences
Write. PATCH https://api.ken.so/v1/me/notification-preferences
Body (json): dailyBrief object, preferences array
Update the caller's notification preferences or daily brief. Send only the changed events. Unknown event keys reject the request.
PATCH /api/v1/me/notification-preferences with Ken-Version 1.1. Internal exposure. Send preferences, daily_brief, or both. preferences is a non-empty list of objects with eventKey (string), isEnabled (boolean, the Email toggle) and optional channels. channels is an object with any subset of inApp, email, slack and teams (booleans); absent channels are unchanged. isEnabled and channels.email are the same toggle and must agree, and every item needs one of them: to change only In app, Slack or Teams, pass the current isEnabled from account(operation="get-notification-preferences"). event_key, is_enabled and in_app are accepted aliases. Unknown event keys reject the whole request, and so does an always-on (isLocked) event unless the caller is a super admin. In app, Slack and Teams on an accounts event need the notifications feature. daily_brief is an object with time (HH:mm, 00:00 to 23:59) and/or timeZone (IANA id such as Europe/Bucharest; time_zone is an alias). Response envelope: success plus the updated preferences.
update-preferences
Write. PATCH https://api.ken.so/v1/me/preferences
Body (json): advanceAfterDone boolean, sharePageContext boolean, showShortcutHints boolean, theme string, whatsNew object
Update the caller's synced app preferences. Omit a field to leave it unchanged. theme "" clears the theme.
PATCH /api/v1/me/preferences with Ken-Version 1.1. Internal exposure. show_shortcut_hints, advance_after_done and share_page_context are booleans; omit one to leave it unchanged. theme is light, dark, or system; pass an empty string to clear it (sent as null, so the app falls back to its own default). Any other theme is refused before the request is sent. Response envelope: success plus data (the full preferences, same shape as account(operation="get-preferences")).