Skip to Content
AI

Agent work

The agent work queue: the work a workspace gave its own coding agent in the agent work settings, handed out through claims. An agent reads what waits, claims a batch of one kind, writes the answers on its own AI plan and submits them; Kenso checks the format and stores each accepted answer where its own AI would have. Work is built when it is claimed, and a claim holds its items until it expires, is released or every item is answered. Behind the agent_work feature, and never open to a Client seat. Each claim, answer and release needs the access the route that writes the same thing by hand declares: Campaigns edit for the campaign kinds, Meetings edit for meeting_brief, Accounts edit for call_brief and Workflows edit for workflow_prompt.

AI4 endpointsKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Path parameters

The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.

NameInTypeRequiredDescription
claimIdpathstringrequired

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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 date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe 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.

Get the agent work queue

GET/v1/agent-workagent-work.get
Permission
Any workspace member except a Network member
Rate limit
12,000 requests a minute per API key
Needs the agent_work feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Returns every kind, always all eight in hand-out order, with its executor, the items waiting for your agent (waiting), the items held by open claims (claimed), what holds the kind back (heldBy: billing_blocked, out_of_credits or ai_paused, else null) and when an answer of it was last accepted. With campaignId, the counts are that campaign's and executor is the campaign's: its override, else the workspace's. Without it, executor is the workspace's switch and waiting counts every campaign your agent takes, including a campaign that gives a kind to your agent while the workspace keeps it on kenso_ai. So read waiting, not executor, to tell whether there is work. Kinds you may not write are listed too. scope picks the campaigns the campaign kinds (qualification, segmentation, personalization, rewriting) count: all (the default) is every campaign that is not deleted or AI-paused, a Draft, finished or errored one included; live is only the campaigns Kenso's AI works on by itself, so an unattended runner gets only work Kenso's AI would have done. The other kinds count the same in both.

Errors:

  • 400 validation_failed: scope is not all or live.
  • 404 not_found: the workspace does not have the agent_work feature, or the campaign is not the workspace's.
  • 503 service_unavailable with Retry-After: the agent work settings could not be read. Try again.

Open to any workspace member except a Client seat.

Parameters

NameInTypeRequiredDescription
campaignIdqueryinteger (int64)optionalOptional. One campaign's counts instead of the workspace's.
scopequerystringoptionalOptional. all (the default) or live: only the campaigns Kenso's AI works on by itself.
Request
curl -X GET "https://api.ken.so/v1/agent-work" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a AgentWorkStatus.

Show the 1 response field and an example

The fields and an example are also on this endpoint's Markdown page.

Claim agent work

POST/v1/agent-work/claimsagent-work.create-claim
Permission
Any workspace member except a Network member
Rate limit
120 requests a minute and 1,800 an hour per workspace
Needs the agent_work feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Hands out up to limit items (1 to 50, default 10) of the first kind, in hand-out order, that waits for your agent and that you may write: only the kinds in kinds when you send it, only campaignId's work when you send it. A kind on kenso_ai, one Kenso cannot hand out yet, or one held back (heldBy) is skipped. With scope live a campaign kind hands out only the campaigns Kenso's AI works on by itself, never a Draft, finished or errored one; all, the default, hands out every campaign's. One claim holds one kind, and one campaign for a campaign kind. The claim holds its items for leaseMinutes (5 to 240, default 30): Kenso's AI and other claims leave them alone until then. Each item carries its target, the prompt Kenso's AI would have run and what the answer must look like (answer.format json or text, and answer.schema, a JSON Schema object or null). Nothing waiting is 200 with id null and no items, and stores no claim. A claim stops short of limit when its items would pass about 900 KB; the rest stay in the queue. Send an Idempotency-Key to retry safely: a resend with the same key returns the same claim.

Errors:

  • 400 validation_failed: an unknown kind, an empty kinds, limit or leaseMinutes out of range, or a scope other than all or live. Each problem is one details[] entry, such as kinds[1].
  • 404 not_found: the workspace does not have the agent_work feature, or the campaign is not the workspace's.
  • 429 rate_limited: more than 120 claims a minute or 1,800 an hour for the workspace.
  • 503 service_unavailable with Retry-After: the agent work settings could not be read. Nothing was handed out. Try again.

Open to any workspace member except a Client seat; hands out only the kinds the caller may write.

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringoptionalA 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.

Request body

application/json, optional.

FieldTypeRequiredDescription
kindsarray of stringoptionalThe kinds to take, in any order; left out for every kind. Kinds are still handed out in hand-out order.
campaignIdinteger (int64)optionalOnly this campaign's work (campaign kinds). The campaign must be the workspace's.
limitinteger (int32)optionalThe most items to take, 1 to 50. Default 10.
leaseMinutesinteger (int32)optionalHow long the claim holds its items, in minutes, 5 to 240. Default 30.
scopestringoptionalWhich campaigns' work a campaign kind hands out: all (the default) is every campaign that is not deleted or AI-paused, a Draft, finished or errored one included; live is only the campaigns Kenso's AI works on by itself. Kinds outside a campaign hand out the same in both.
Request
curl -X POST "https://api.ken.so/v1/agent-work/claims" \
  -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 '{
  "kinds": [
    "string"
  ],
  "campaignId": 812,
  "limit": 1,
  "leaseMinutes": 1,
  "scope": "all"
}'

Response 200

data is a AgentWorkClaim.

Show the 5 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Submit agent work answers

POST/v1/agent-work/claims/{claimId}/answersagent-work.submit-answers
Permission
Any workspace member except a Network member
Rate limit
300 requests a minute and 6,000 an hour per workspace
Needs the agent_work feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Takes in up to 50 answers to the claim's items: { "agent": { "cli", "model" }, "answers": [ { "itemId", "output" } ] }. output is a JSON object for a json item and a string for a text item, at most 64 KB. Returns one result per answer, in the order sent: accepted (stored where Kenso's AI would have stored it); rejected with a reason (invalid_format, too_large, unknown_item or a check the answer failed; the item is closed and its work goes back to the queue); expired (the claim ran out or was released, or the record no longer needs an answer); duplicate (the item already has an answer, or one is being taken in). Each result also has retryable: true only when Kenso could not take the answer in and the item is still held (rejected with failed_checks), so send that answer again; false for every other result. Always 200 when the claim exists, whatever each answer's result. Answer items of a claim in as many calls as you like: the claim closes once every item is answered. The agent's cli and model are saved on the claim. Send an Idempotency-Key to retry safely: an answer stored once is never stored twice.

Errors:

  • 400 validation_failed: no answers, more than 50, an answer that is not an object, or an agent name over 100 characters.
  • 403 forbidden: you may not write the claim's kind.
  • 404 not_found: the workspace does not have the agent_work feature, or the claim is not the workspace's.
  • 429 rate_limited: more than 300 submits a minute or 6,000 an hour for the workspace.

Open to any workspace member except a Client seat who may write the claim's kind.

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringoptionalA 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.

Request body

application/json, optional.

FieldTypeRequiredDescription
agentAgentWorkAgentBodyoptionalThe agent that wrote the answers, saved on the claim. Optional.
answersarray of AgentWorkAnswerBodyoptional1 to 50 answers, each to an item of this claim.
Request
curl -X POST "https://api.ken.so/v1/agent-work/claims/01JC8Z3K6Q2W4M7N9P5R1T3V5X/answers" \
  -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 '{
  "agent": {
    "cli": "claude-code",
    "model": "string"
  },
  "answers": [
    {
      "itemId": "string",
      "output": null
    }
  ]
}'

Response 200

data is a AgentWorkSubmit.

Show the 3 response fields and an example

The fields and an example are also on this endpoint's Markdown page.

Release an agent work claim

DELETE/v1/agent-work/claims/{claimId}agent-work.release-claim
Permission
Any workspace member except a Network member
Rate limit
4,800 requests a minute per API key
Needs the agent_work feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

Gives the claim's unanswered items back to the queue now and closes the claim; answers already stored stay. Returns how many items went back. Releasing a claim that is already closed (answered, released or expired) is 200 with released 0.

Errors:

  • 403 forbidden: you may not write the claim's kind.
  • 404 not_found: the workspace does not have the agent_work feature, or the claim is not the workspace's.

Open to any workspace member except a Client seat who may write the claim's kind.

Request
curl -X DELETE "https://api.ken.so/v1/agent-work/claims/01JC8Z3K6Q2W4M7N9P5R1T3V5X" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"

Response 200

data is a AgentWorkRelease.

Show the 1 response field and an example

The fields and an example are also on this endpoint's Markdown page.


On this page