Agent Work agent_work
Who runs each kind of Kenso AI work that can wait: Kenso's AI (kenso_ai) or the workspace's own coding agent (my_agent), which collects it with kenso work run. settings-update switches only the kinds it names. get, create-claim, submit-answers and release-claim do that work by hand: read what waits, take a claim, answer it, give the rest back. Needs the agent_work flag. sandbox-connections-list shows the agents connected in the person's own Kenso sandbox; they connect one in the app. sandbox-runs-* run that sandbox, which works the queue with a connected agent; estimate first. sandbox-auto-runs-get shows whether Kenso may start the person's sandbox by itself.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through agent_work_read and changes through agent_work_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: sandbox-runs-cancel, sandbox-runs-create, create-claim, sandbox-connections-disconnect, sandbox-auto-runs-get, sandbox-runs-get, get, settings-get, sandbox-connections-list, sandbox-runs-list, release-claim, submit-answers, sandbox-auto-runs-update, settings-update, sandbox-auto-runs-update-workspace
sandbox-runs-cancel
Write. Early access: needs agent_sandboxes, agent_work on for the workspace. POST https://api.ken.so/v1/agent-sandbox-runs/{runId}/cancel
Path: runId
Stop one of your sandbox runs.
POST /api/v1/agent-sandbox-runs/{runId}/cancel. Sends Ken-Version 1.1. Consent scope campaigns.
Answers with the run as it reads right after the stop request, stopRequestedAt set; its status changes on the run
supervisor's next pass, within about 20 seconds. Asking again is safe. A queued run then ends (endReason stopped) without starting and nothing is charged.
A running run stops; its claims go back to the queue and the minutes it ran are charged. An ended run comes back
as it is. Read it again with sandbox-runs-get to see the end.
sandbox-runs-create
Write. Early access: needs agent_sandboxes, agent_work on for the workspace. POST https://api.ken.so/v1/agent-sandbox-runs
Body (json): agent string, campaignId integer, estimateOnly boolean, kinds array, maxCeilingCredits number
Estimate or start a run of your own Kenso sandbox, which empties the agent work queue with your agent. Ask with estimate_only=true first, show the person the cost, then start with max_ceiling_credits set to the ceilingCredits they saw. Needs both flags; never a Client seat.
POST /api/v1/agent-sandbox-runs. Sends Ken-Version 1.1. Consent scope campaigns. agent (required): claude, codex, antigravity, opencode, grok or cursor, one the person connected in the app. campaign_id: only that campaign's work (left out: the whole workspace). kinds: agent work kinds (meeting_brief, call_brief, workflow_prompt, qualification, segmentation, personalization, rewriting); left out for every kind on My agent. A run works only the kinds the person may write. estimate_only=true answers 200 with data.estimate only (waitingItems, expectedMinutes, ceilingMinutes, ceilingCredits, creditsPerHour) and creates nothing. Otherwise Kenso holds ceilingCredits and answers 202 with the run (data.id asr_..., status queued); it charges the started minutes when the run ends and releases the rest. A run is created even when nothing is waiting: it ends queue_empty within a minute or two and is charged one minute. max_ceiling_credits: the estimate's ceilingCredits the person saw; a start whose ceiling is now higher is 409 estimate_changed and holds nothing (ask for the estimate again and show it). Left out: no check. 409 agent_not_connected: the person connects the agent in the app first (an agent never logs in for them). 409 run_active: the person already has a live run. 402 plan_limit_reached (refusal INSUFFICIENT_CREDITS): the workspace cannot cover the ceiling. 402 member_credit_limit_reached: the ceiling is more than is left of the person's monthly credit limit. 403 forbidden: the person may write none of the kinds in scope (the estimate too). 404 not_found where a flag is off. 503 with Retry-After: settings or credits could not be read, or the run could not be confirmed.
create-claim
Write. Early access: needs agent_work on for the workspace. POST https://api.ken.so/v1/agent-work/claims
Body (json): campaignId integer, kinds array, leaseMinutes integer, limit integer
Take a batch of waiting AI work of one kind to answer, with its prompts. One claim holds one kind. Answer with submit-answers before it expires.
POST /api/v1/agent-work/claims. Public where the agent_work flag is on. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Consent scope campaigns.
kinds (optional): the kinds to look at, in hand-out order; left out, every kind. Kenso hands out items of the
first kind that has any, skipping kinds that are on kenso_ai, kinds the caller may not write and kinds Kenso
cannot hand out yet. campaign_id (optional) takes one campaign's work only. limit 1 to 50 (default 10); a claim
stops short of limit when its items would pass about 900 KB.
lease_minutes 5 to 240 (default 30): the claim expires then and its unanswered items go back to the queue.
idempotency_key (optional, 1 to 200 characters) is sent as Idempotency-Key: a retry with the same key returns
the same claim instead of taking more items.
Returns data: id (awc_..., null when nothing waits), kind, campaignId, expiresAt and items. Each item has
id (awi_...), kind, target {type, id, campaignId}, prompt {system, user}, answer {format (json or text), schema
(JSON Schema object or null), instruction}. The prompts carry the lead's facts: use them only for the answer.
An empty queue is 200 with id null and no items. 400 validation_failed on an unknown kind or a limit out of
range; 429 rate_limited (Retry-After); 503 service_unavailable (Retry-After): try again.
sandbox-connections-disconnect
Write. Early access: needs agent_sandboxes, agent_work on for the workspace. DELETE https://api.ken.so/v1/agent-sandbox/connections/{agent}
Path: agent
Disconnect an agent CLI from your own Kenso sandbox. The person must log in again in the app to use it there. Confirm with them first.
DELETE /api/v1/agent-sandbox/connections/{agent}. Sends Ken-Version 1.1. Consent scope campaigns.
agent: claude, codex, antigravity, opencode, grok or cursor. Logs the CLI out in the box; with no agent left
connected the sandbox itself is deleted. Returns data {agent, status: "not_connected"}, also for an agent that was
not connected. 409 run_active while a sandbox run is live: the person stops the run in the app first.
sandbox-auto-runs-get
Read. Early access: needs agent_sandboxes, agent_work on for the workspace. GET https://api.ken.so/v1/agent-sandbox/auto-run-settings
Read your automatic Kenso sandbox runs: your switch and agent, and the workspace's cap and wait. Needs both flags; never a Client seat.
GET /api/v1/agent-sandbox/auto-run-settings. Sends Ken-Version 1.1.
Returns data {enabled, agent (claude, codex, antigravity, opencode, grok, cursor or null), monthlyCapCredits,
waitMinutes}. Nothing saved reads as enabled false, agent null, monthlyCapCredits 0 (no automatic run starts) and
waitMinutes 60. 404 not_found where a flag is off.
sandbox-runs-get
Read. Early access: needs agent_sandboxes, agent_work on for the workspace. GET https://api.ken.so/v1/agent-sandbox-runs/{runId}
Path: runId
Read one of your sandbox runs with its progress.
GET /api/v1/agent-sandbox-runs/{runId}. Sends Ken-Version 1.1. run_id: the asr_... id.
status: queued, starting, running, stopping or ended (endReason queue_empty, stopped, usage_limit, max_length,
credits_used, agent_logged_out, answer_refused or failed). accepted and rejected count answers so far, waiting
the items still waiting in its scope, minutes and credits the time so far (the billed ones once ended).
stopRequestedAt is set once a stop was asked for. 404 not_found for a run of another person or workspace.
get
Read. Early access: needs agent_work on for the workspace. GET https://api.ken.so/v1/agent-work
Query: campaignId integer
Show how much AI work waits for the workspace's own agent, per kind. Start here before create-claim. Needs the agent_work flag; never a Client seat.
GET /api/v1/agent-work. Public where the agent_work flag is on. Sends Ken-Version 1.1.
campaign_id (optional) counts one campaign's work only; another workspace's campaign is 404.
Returns data.kinds: all seven kinds in hand-out order (meeting_brief, call_brief, workflow_prompt,
qualification, segmentation, personalization, rewriting), each with kind, executor (kenso_ai or my_agent),
waiting (items ready to hand out; 0 when the kind is on kenso_ai or Kenso cannot hand it out yet), claimed
(items held by open claims), heldBy (null, or billing_blocked, out_of_credits or ai_paused: nothing of that
kind is handed out until it clears) and lastAcceptedAt.
Doing a small job by hand, in this chat:
1. agent_work(operation="get") and pick a kind with waiting above 0.
2. agent_work(operation="create-claim", kinds=["<kind>"], limit=5) to take up to 5 items.
3. For each item, follow its prompt.system and prompt.user and write an answer in answer.format
(an object matching answer.schema for json, plain text for text), as answer.instruction says.
4. agent_work(operation="submit-answers", claim_id="awc_...", answers=[{"item_id": "awi_...", "output": ...}]).
5. If you stop early, agent_work(operation="release-claim", claim_id="awc_...") gives the rest back.
503 service_unavailable (Retry-After) when Kenso cannot read the workspace's settings for a moment: try again.
404 not_found where the agent_work flag is off.
settings-get
Read. Early access: needs agent_work on for the workspace. GET https://api.ken.so/v1/agent-work-settings
Return who runs each kind of AI work that can wait: Kenso's AI or the workspace's own agent. Always all seven kinds. Needs the agent_work flag; never a Client seat.
GET /api/v1/agent-work-settings. Public where the agent_work flag is on. Sends Ken-Version 1.1. client_id is sent as X-Ken-Workspace-Id. Returns data.settings: one entry per kind, in hand-out order (meeting_brief, call_brief, workflow_prompt, qualification, segmentation, personalization, rewriting), each with kind, executor (kenso_ai, the default, or my_agent) and updatedAt (null for a kind the workspace never saved). my_agent means the workspace's own coding agent collects that work with `kenso work run` and runs it on the customer's own AI plan; Kenso's AI does not run it. 404 not_found where the agent_work flag is off.
sandbox-connections-list
Read. Early access: needs agent_sandboxes, agent_work on for the workspace. GET https://api.ken.so/v1/agent-sandbox/connections
List which agent CLIs are connected in your own Kenso sandbox. Always six. Needs both flags; never a Client seat.
GET /api/v1/agent-sandbox/connections. Sends Ken-Version 1.1. Returns the canonical list envelope: data is claude, codex, antigravity, opencode, grok and cursor in that order, each with status (connected or not_connected), connectedAt and lastRunAt; pagination.hasMore is always false. No field holds a token, a code or a file path. To connect an agent the person presses Connect in the app (Settings > Ken agent > Kenso sandbox); never offer to do it. 404 not_found where a flag is off.
sandbox-runs-list
Read. Early access: needs agent_sandboxes, agent_work on for the workspace. GET https://api.ken.so/v1/agent-sandbox-runs
Query: active boolean, cursor string, limit integer
List your own sandbox runs in the workspace, newest first.
GET /api/v1/agent-sandbox-runs. Sends Ken-Version 1.1. active=true: only live runs (queued, starting, running, stopping). limit: 1 to 50, default 20. cursor: the previous page's pagination.nextCursor, unchanged, with the same active. Returns data, the array of runs, each with id, agent, status, endReason, accepted, rejected, waiting, minutes, credits and estimate; pagination.hasMore is true when older runs follow, and pagination.nextCursor reads them.
release-claim
Write. Early access: needs agent_work on for the workspace. DELETE https://api.ken.so/v1/agent-work/claims/{claimId}
Path: claimId
Give a claim's unanswered items back to the queue now. Use it when you stop before answering every item.
DELETE /api/v1/agent-work/claims/{claimId}. Public where the agent_work flag is on. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Consent scope campaigns.
claim_id: the awc_... id from create-claim. Answers already sent stay as they are.
Returns data.released: how many items went back. A claim that is already closed or expired returns 0.
404 not_found for a claim of another workspace or one that does not exist; 403 forbidden when the caller may
not write the claim's kind.
submit-answers
Write. Early access: needs agent_work on for the workspace. POST https://api.ken.so/v1/agent-work/claims/{claimId}/answers
Path: claimId
Body (json): agent object, answers array
Send answers for items of a claim; each gets its own result. Up to 50 answers a call; send the rest in another call.
POST /api/v1/agent-work/claims/{claimId}/answers. Public where the agent_work flag is on. Sends Ken-Version 1.1
and X-Ken-Actor: agent. Consent scope campaigns.
claim_id: the awc_... id from create-claim.
answers: [{"item_id": "awi_...", "output": ...}], 1 to 50. output is an object matching the item's
answer.schema for a json item, and a string for a text item; at most 64 KB.
agent (optional): {"cli": "claude-code", "model": "..."}, each 100 characters or fewer, saved on the claim.
idempotency_key (optional, 1 to 200 characters) is sent as Idempotency-Key, so a retry is answered once.
Returns data: results (one per answer, in order: itemId, status, reason, message, retryable), accepted and
rejected. status is accepted; rejected (reason unknown_item, too_large, invalid_format, schema_mismatch,
wrong_language, leaked_reasoning, failed_checks or human_written, with a message saying why); expired (the claim
or item ran out, was released, or its lead is gone); duplicate (the item was already answered, or an answer to it
is being taken in). A rejected item is closed: Kenso takes no other answer for it, and its work may come back in a
later claim. retryable is true only when Kenso could not take the answer in and the item is still held (rejected
with failed_checks): send that answer again. Never send again an answer whose retryable is false.
404 not_found for a claim of another workspace or one that does not exist; 403 forbidden when the caller may
not write the claim's kind.
sandbox-auto-runs-update
Write. Early access: needs agent_sandboxes, agent_work on for the workspace. PATCH https://api.ken.so/v1/agent-sandbox/auto-run-settings
Body (json): agent string, enabled boolean
Turn your own automatic Kenso sandbox runs on or off, or change the agent Kenso starts. Runs spend the workspace's credits: only after the person says yes.
PATCH /api/v1/agent-sandbox/auto-run-settings. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Consent scope campaigns. enabled and agent, either or both. agent: claude, codex, antigravity, opencode, grok or cursor; turning on needs it connected in the person's Kenso sandbox (they connect it in the app). Returns the settings as sandbox-auto-runs-get does. 400 validation_failed on an empty change or on with no agent; 409 agent_not_connected; 404 where a flag is off.
settings-update
Write. Early access: needs agent_work on for the workspace. PATCH https://api.ken.so/v1/agent-work-settings
Body (json): settings array
Set who runs the named kinds of AI work; kinds left out stay as they are. Each entry is {kind, executor}. Requires the `workspace_settings` permission.
PATCH /api/v1/agent-work-settings. Public where the agent_work flag is on. Sends Ken-Version 1.1 and
X-Ken-Actor: agent. Consent scope workspace:admin.
settings: [{"kind": "personalization", "executor": "my_agent"}], at least one entry, each kind at most once.
kind is meeting_brief, call_brief, workflow_prompt, qualification, segmentation, personalization or rewriting.
executor is kenso_ai (Kenso's AI runs it, the default) or my_agent (the workspace's own coding agent collects it
with `kenso work run`). With my_agent the kind's work waits for that agent: Kenso's AI does not run it, and the
full prompt and the lead's facts go to the agent. Only switch a kind after the user says yes.
Returns every kind after the change, as settings-get does. 400 validation_failed on an unknown kind or executor,
an empty list or a kind named twice (nothing is saved); 404 not_found where the agent_work flag is off.
sandbox-auto-runs-update-workspace
Write. Early access: needs agent_sandboxes, agent_work on for the workspace. PATCH https://api.ken.so/v1/agent-sandbox/auto-run-settings/workspace
Body (json): monthlyCapCredits integer, waitMinutes integer
Set the workspace's monthly credit cap on automatic Kenso sandbox runs, and how long work waits first. Requires the workspace_settings permission. Spending: only after the person says yes.
PATCH /api/v1/agent-sandbox/auto-run-settings/workspace. Sends Ken-Version 1.1 and X-Ken-Actor: agent. Consent scope workspace:admin. monthly_cap_credits 0 to 100000 (0 starts none; counts only automatic runs, per calendar month UTC) and wait_minutes 15 to 1440, either or both. Returns the settings as sandbox-auto-runs-get does.