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

# Kenso API changes on 2026-11-12

> **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.

Every change on this day, by version. The [changelog](/docs/changelog) lists the newest days and links the older ones. The changelog in Markdown: [/docs/changelog.md](/docs/changelog.md).

## Version 2026-11-02

### 2026-11-12 (49 changes)

- **Added**: Accepts an optional Idempotency-Key header (at most 200 characters, per workspace). A retry with the same key and the same request within 24 hours returns the first response, with Idempotent-Replayed: true, and does not run the write again. The same key with a different request is 422 idempotency_key_reused. - [`tags.assign`](/docs/api/tags/assign.md)
- **Added**: Accepts an optional Idempotency-Key header (at most 200 characters, per workspace). A retry with the same key and the same request within 24 hours returns the first response, with Idempotent-Replayed: true, and does not run the write again. The same key with a different request is 422 idempotency_key_reused. - [`tags.bulk-assign`](/docs/api/tags/bulk-assign.md)
- **Added**: Accepts an optional Idempotency-Key header (at most 200 characters, per workspace). A retry with the same key and the same request within 24 hours returns the first response, with Idempotent-Replayed: true, and does not run the write again. The same key with a different request is 422 idempotency_key_reused. - [`tags.bulk-unassign`](/docs/api/tags/bulk-unassign.md)
- **Added**: Accepts an optional Idempotency-Key header (at most 200 characters, per workspace). A retry with the same key and the same request within 24 hours returns the first response, with Idempotent-Replayed: true, and does not run the write again. The same key with a different request is 422 idempotency_key_reused. - [`tags.unassign`](/docs/api/tags/unassign.md)
- **Changed**: Added optional field opensTracked to the metrics of the analytics.get-campaign-performance response (window metrics and rows). false means the campaign sends as plain text or has Track opens off, so its openRate is not a real rate: opens are partial, not none. Omitted when the call spans campaigns or the value is unknown; treat omitted like true. - [`analytics.get-campaign-performance`](/docs/api/analytics/get-campaign-performance.md)
- **Changed**: Added optional fields `data[].health.notes`, `data[].health.notes[].kind`, `data[].health.notes[].reason` and `data[].health.notes[].until` to the campaigns.list-inboxes response. health.blocks no longer lists an automatic pause that holds no send (any pause Kenso opened itself, such as after a placement test, bounces, complaints or a domain breach, while capacity limits are not enforced); it shows as a health.notes item with kind sending_pause_observed. An operator's pause still shows as a sending_paused block. - [`campaigns.list-inboxes`](/docs/api/campaigns/list-inboxes.md)
- **Changed**: Added optional fields `data[].health.notes`, `data[].health.notes[].kind`, `data[].health.notes[].reason` and `data[].health.notes[].until` to the campaigns.replace-inboxes response. health.blocks no longer lists an automatic pause that holds no send (any pause Kenso opened itself, such as after a placement test, bounces, complaints or a domain breach, while capacity limits are not enforced); it shows as a health.notes item with kind sending_pause_observed. An operator's pause still shows as a sending_paused block. - [`campaigns.replace-inboxes`](/docs/api/campaigns/replace-inboxes.md)
- **Changed**: Added optional fields `data.health.notes`, `data.health.notes[].kind`, `data.health.notes[].reason` and `data.health.notes[].until` to the inboxes.create response. health.blocks no longer lists an automatic pause that holds no send (any pause Kenso opened itself, such as after a placement test, bounces, complaints or a domain breach, while capacity limits are not enforced); it shows as a health.notes item with kind sending_pause_observed. An operator's pause still shows as a sending_paused block. - [`inboxes.create`](/docs/api/inboxes/create.md)
- **Changed**: Added optional fields `data.health.notes`, `data.health.notes[].kind`, `data.health.notes[].reason` and `data.health.notes[].until` to the inboxes.disconnect response. health.blocks no longer lists an automatic pause that holds no send (any pause Kenso opened itself, such as after a placement test, bounces, complaints or a domain breach, while capacity limits are not enforced); it shows as a health.notes item with kind sending_pause_observed. An operator's pause still shows as a sending_paused block. - [`inboxes.disconnect`](/docs/api/inboxes/disconnect.md)
- **Changed**: Added optional fields `data.health.notes`, `data.health.notes[].kind`, `data.health.notes[].reason` and `data.health.notes[].until` to the inboxes.get response. health.blocks no longer lists an automatic pause that holds no send (any pause Kenso opened itself, such as after a placement test, bounces, complaints or a domain breach, while capacity limits are not enforced); it shows as a health.notes item with kind sending_pause_observed. An operator's pause still shows as a sending_paused block. - [`inboxes.get`](/docs/api/inboxes/get.md)
- **Changed**: Added optional fields `data[].health.notes`, `data[].health.notes[].kind`, `data[].health.notes[].reason` and `data[].health.notes[].until` to the inboxes.list response. health.blocks no longer lists an automatic pause that holds no send (any pause Kenso opened itself, such as after a placement test, bounces, complaints or a domain breach, while capacity limits are not enforced); it shows as a health.notes item with kind sending_pause_observed. An operator's pause still shows as a sending_paused block. - [`inboxes.list`](/docs/api/inboxes/list.md)
- **Changed**: Added optional fields `data.inbox.health.notes`, `data.inbox.health.notes[].kind`, `data.inbox.health.notes[].reason` and `data.inbox.health.notes[].until` to the inboxes.rename response. health.blocks no longer lists an automatic pause that holds no send (any pause Kenso opened itself, such as after a placement test, bounces, complaints or a domain breach, while capacity limits are not enforced); it shows as a health.notes item with kind sending_pause_observed. An operator's pause still shows as a sending_paused block. - [`inboxes.rename`](/docs/api/inboxes/rename.md)
- **Changed**: Added optional fields `data.health.notes`, `data.health.notes[].kind`, `data.health.notes[].reason` and `data.health.notes[].until` to the inboxes.update response. health.blocks no longer lists an automatic pause that holds no send (any pause Kenso opened itself, such as after a placement test, bounces, complaints or a domain breach, while capacity limits are not enforced); it shows as a health.notes item with kind sending_pause_observed. An operator's pause still shows as a sending_paused block. - [`inboxes.update`](/docs/api/inboxes/update.md)
- **Changed**: Added optional fields `data.health.notes`, `data.health.notes[].kind`, `data.health.notes[].reason` and `data.health.notes[].until` to the inboxes.verify response. health.blocks no longer lists an automatic pause that holds no send (any pause Kenso opened itself, such as after a placement test, bounces, complaints or a domain breach, while capacity limits are not enforced); it shows as a health.notes item with kind sending_pause_observed. An operator's pause still shows as a sending_paused block. - [`inboxes.verify`](/docs/api/inboxes/verify.md)
- **Added**: Added agent-sandbox-connections.list (GET /v1/agent-sandbox/connections): the six agent CLIs in your own Kenso sandbox, each connected or not_connected, with connectedAt and lastRunAt. Behind the agent_work and agent_sandboxes features. - [`agent-sandbox-connections.list`](/docs/api/agent-sandbox-connections/list.md)
- **Added**: Added agent-sandbox-connections.disconnect (DELETE /v1/agent-sandbox/connections/{agent}): logs an agent CLI out in your own Kenso sandbox; with no agent left connected the sandbox is deleted. 409 run_active while a sandbox run is live. Behind the agent_work and agent_sandboxes features. - [`agent-sandbox-connections.disconnect`](/docs/api/agent-sandbox-connections/disconnect.md)
- **Added**: Added agent-sandbox-runs.create: estimate a run of the caller's own Kenso sandbox, which works the agent work queue with the coding agent they connected (estimateOnly: true answers 200 with the estimate and creates nothing), or hold its ceiling in credits and queue the run (202 with the run). Available to workspaces with agent sandboxes turned on. - [`agent-sandbox-runs.create`](/docs/api/agent-sandbox-runs/create.md)
- **Added**: Added agent-sandbox-runs.list: the caller's own sandbox runs in the workspace, newest first, with cursor pagination (limit 1 to 50, default 20); active=true lists only live runs. Available to workspaces with agent sandboxes turned on. - [`agent-sandbox-runs.list`](/docs/api/agent-sandbox-runs/list.md)
- **Added**: Added agent-sandbox-runs.get: one of the caller's sandbox runs with its progress (accepted and rejected answers, waiting items, minutes and credits so far, the billed ones once it ended). Available to workspaces with agent sandboxes turned on. - [`agent-sandbox-runs.get`](/docs/api/agent-sandbox-runs/get.md)
- **Added**: Added agent-sandbox-runs.cancel: asks Kenso to stop one of the caller's sandbox runs and answers with the run; a queued run ends without starting and is not charged, a running one stops and is charged the minutes it ran. Available to workspaces with agent sandboxes turned on. - [`agent-sandbox-runs.cancel`](/docs/api/agent-sandbox-runs/cancel.md)
- **Changed**: Added optional field data.stopRequestedAt to the agent-sandbox-runs.create 202 response: when the person asked to stop the run, null until then. - [`agent-sandbox-runs.create`](/docs/api/agent-sandbox-runs/create.md)
- **Added**: Added agent-sandbox-auto-run-settings.get: read whether Kenso may start the caller's own Kenso sandbox by itself in this workspace (enabled and agent), and the workspace's monthly credit cap on those automatic runs and how long work waits before one starts. Available to workspaces with agent sandboxes turned on. - [`agent-sandbox-auto-run-settings.get`](/docs/api/agent-sandbox-auto-run-settings/get.md)
- **Added**: Added agent-sandbox-auto-run-settings.update: turn the caller's own automatic sandbox runs on or off in this workspace, or change the agent Kenso starts. Turning on needs that agent connected in the caller's Kenso sandbox. Available to workspaces with agent sandboxes turned on. - [`agent-sandbox-auto-run-settings.update`](/docs/api/agent-sandbox-auto-run-settings/update.md)
- **Added**: Added agent-sandbox-auto-run-settings.update-workspace: set the workspace's monthly credit cap on automatic sandbox runs (0 to 100000; 0 starts none) and how long work waits before Kenso starts a sandbox (15 to 1440 minutes). Requires the workspace settings permission. Available to workspaces with agent sandboxes turned on. - [`agent-sandbox-auto-run-settings.update-workspace`](/docs/api/agent-sandbox-auto-run-settings/update-workspace.md)
- **Changed**: Added optional field `data.person.phoneFind.reason` to the people.intake response. The person model's phoneFind gained reason: suppressed when the newest phone find failed because Kenso may not contact the person (on the blocklist, unsubscribed, marked do not contact, or opted out of phone contact), so it asked no source and charged nothing, and the app should not offer to try again; absent otherwise. Only the people get, list and search reads fill phoneFind; people.intake leaves it out. Only an iMessage phone find carries it, which needs the imessage feature, off for every workspace for now. - [`people.intake`](/docs/api/people/intake.md)
- **Changed**: On an iMessage thread, a read of the ready voice note that fails now fails the read with 500 internal_error (it left imessage.voiceNoteReady out), so a missing voiceNoteReady always means there is no ready note: try the read again. Needs the imessage feature, which is off for every workspace for now. - [`threads.get`](/docs/api/threads/get.md)
- **Changed**: On an iMessage thread, interest is no longer replaced by the class of an older text that reaches Kenso after a newer one: a late text no longer overwrites a newer interested or objection class, or a newer refusal. A late stop in free text (read by Kenso's classifier) opts the number out unless the newer class is interested or objection; an exact STOP, UNSUBSCRIBE, END, QUIT or CANCEL always opts it out. Needs the imessage feature, which is off for every workspace for now. - [`threads.get`](/docs/api/threads/get.md)
- **Changed**: A note for a person Kenso may not text is 409 invalid_state with error.details[0].code phone_opt_out (a STOP on the number or the person's opt-out of texts), do_not_call (a data provider flagged the person do not call) or suppressed:<reason> (the blocklist, do-not-contact or an unsubscribe), on touchId, threadId or else personId, and nothing is written, spoken or charged. A note for a touchId is also 409 invalid_state with error.details[0].code suppressed:blocklisted on touchId when a domain of the touch's account is on the blocklist, as the text's send would fail it, and nothing is written, spoken or charged. A note for a threadId still reads the person alone. Needs the imessage feature, which is off for every workspace for now. - [`voice-notes.create`](/docs/api/voice-notes/create.md)

Optional fields added on 21 operations:

- **Changed**: Added optional field `data.listeningIdleReason` to the triggers.create response. - [`triggers.create`](/docs/api/triggers/create.md)
- **Changed**: Added optional field `data.listeningIdleReason` to the triggers.get response. - [`triggers.get`](/docs/api/triggers/get.md)
- **Changed**: Added optional field `data[].listeningIdleReason` to the triggers.list response. - [`triggers.list`](/docs/api/triggers/list.md)
- **Changed**: Added optional fields `data[].sourceKind` and `data[].topic` to the triggers.list-linkedin-engagements response. - [`triggers.list-linkedin-engagements`](/docs/api/triggers/list-linkedin-engagements.md)
- **Changed**: Added optional field `data.listeningIdleReason` to the triggers.update response. - [`triggers.update`](/docs/api/triggers/update.md)
- **Changed**: Added optional field `data.linkedInSendBlockedReason` to the contacts.get response. - [`contacts.get`](/docs/api/contacts/get.md)
- **Changed**: Added optional field `data[].linkedInSendBlockedReason` to the contacts.list response. - [`contacts.list`](/docs/api/contacts/list.md)
- **Changed**: Added optional field `data[].linkedInSendBlockedReason` to the contacts.search response. - [`contacts.search`](/docs/api/contacts/search.md)
- **Changed**: Added optional field `data.linkedInSendBlockedReason` to the contacts.update response. - [`contacts.update`](/docs/api/contacts/update.md)
- **Changed**: Added optional field `data.steps[].warnings` to the linkedin-sequences.get response. - [`linkedin-sequences.get`](/docs/api/linkedin-sequences/get.md)
- **Changed**: Added optional field `data.steps[].warnings` to the linkedin-sequences.replace response. - [`linkedin-sequences.replace`](/docs/api/linkedin-sequences/replace.md)
- **Changed**: Added optional field `data.sequence.steps[].warnings` to the linkedin-sequences.save-version response. - [`linkedin-sequences.save-version`](/docs/api/linkedin-sequences/save-version.md)
- **Changed**: Added optional field `data.steps[].warnings` to the segment-linkedin-sequences.get response. - [`segment-linkedin-sequences.get`](/docs/api/segment-linkedin-sequences/get.md)
- **Changed**: Added optional field `data.steps[].warnings` to the segment-linkedin-sequences.replace response. - [`segment-linkedin-sequences.replace`](/docs/api/segment-linkedin-sequences/replace.md)
- **Changed**: Added optional field `data.sequence.steps[].warnings` to the segment-linkedin-sequences.save-version response. - [`segment-linkedin-sequences.save-version`](/docs/api/segment-linkedin-sequences/save-version.md)
- **Changed**: Added optional field `data.providerHosted` to the domains.get response. - [`domains.get`](/docs/api/domains/get.md)
- **Changed**: Added optional field `data[].providerHosted` to the domains.list response. - [`domains.list`](/docs/api/domains/list.md)
- **Changed**: Added optional field `data.providerHosted` to the domains.update response. - [`domains.update`](/docs/api/domains/update.md)
- **Changed**: Added optional field `data.aiOnly` to the custom-variables.create response. - [`custom-variables.create`](/docs/api/custom-variables/create.md)
- **Changed**: Added optional field `data[].aiOnly` to the custom-variables.list response. - [`custom-variables.list`](/docs/api/custom-variables/list.md)
- **Changed**: Added optional field `data.aiOnly` to the custom-variables.update response. - [`custom-variables.update`](/docs/api/custom-variables/update.md)

- Newer day: [2026-11-13](/docs/changelog/2026-11-13.md)
- Older day: [2026-11-11](/docs/changelog/2026-11-11.md)
- Every change: [/docs/changelog.md](/docs/changelog.md)
