Sandboxes
A sandbox is a workspace of your own, one per member, where sends, domain orders and credit charges are simulated and webhooks still fire. Only its owner can read or change it: another member's sandbox answers not_found. Call these routes with your own sign-in or a live API key; a test key works inside its sandbox and is refused here.
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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
sandboxId | path | integer (int64) | required |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The 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-Id | header | integer (int64) | optional | The 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. |
List your sandboxes
/v1/sandboxessandboxes.list- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
developer_sandboxes feature on your workspace. Until it is on, calls answer 404.Your own sandbox, as a list of zero or one. Never another member's. 404 not_found when the workspace does not have the developer_sandboxes feature. Any workspace member.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer (int32) | optional | Items per page, from 1 to 200. Omit limit and cursor to get every item in one response, as before; with only cursor, 50 per page. |
cursor | query | string | optional | The nextCursor of the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/sandboxes?limit=1" \
-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 list of Sandbox. Each item has these fields. The response also carries pagination.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create your sandbox and its first test key
/v1/sandboxessandboxes.create- Permission
- Any workspace member except a Network member
- Rate limit
- 10 requests a day per user
developer_sandboxes feature on your workspace. Until it is on, calls answer 404.Creates a sandbox workspace of your own, seeded with campaigns, contacts, sequences, threads and analytics, and returns one test key for it. The key's secret (it starts kenso_test_) is returned once: store it now. A test key works only inside its sandbox, on Ken-Version: 1.1 routes: another workspace answers it 404 not_found. Without Ken-Version: 1.1 it reaches only the identity reads GET /v1/me/context and GET /v1/api-keys/validate; every other legacy route, these sandbox routes and the workspace API key routes answer it 403. Nothing in a sandbox leaves Kenso: launching a campaign sends no email, and orders and charges are simulated.
You are the sandbox's only member. One sandbox per member:
409 invalid_statewith the detail codesandbox_exists: you already have one. The detail message names its id; reset or delete it instead.404 not_found: the workspace does not have thedeveloper_sandboxesfeature.429 quota_exceeded: you used your 10 sandbox creates and resets of the last 24 hours. They are counted per member, not per workspace.
Any member of the header workspace can create one, a view-only member included. You are the Admin of your sandbox only: your role in each workspace you belong to stays as it is. A request made with a test key is refused. One made with a live API key of yours is served, so the CLI and a script can create the sandbox: the test key it returns works only inside the sandbox, never in your other workspaces. 403 permission_denied: a test key or another key held to a permission template, or a Client or Network member seat. 403 forbidden: no member is behind the credential.
curl -X POST "https://api.ken.so/v1/sandboxes" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 201
data is a SandboxCreated.
Show the 7 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get your sandbox
/v1/sandboxes/{sandboxId}sandboxes.get- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
developer_sandboxes feature on your workspace. Until it is on, calls answer 404.404 not_found when the id is not your own sandbox, or the workspace does not have the developer_sandboxes feature. Any workspace member.
curl -X GET "https://api.ken.so/v1/sandboxes/812" \
-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 Sandbox.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Delete your sandbox
/v1/sandboxes/{sandboxId}sandboxes.delete- Permission
- Any workspace member except a Network member
- Rate limit
- 4,800 requests a minute per API key
developer_sandboxes feature on your workspace. Until it is on, calls answer 404.Revokes every test key of the sandbox, deletes the data a reset deletes (its campaigns, contacts, sequences, threads, analytics and everything else you created in it) and deletes the sandbox. That data is gone for good; you can create a new sandbox afterwards. What a reset keeps is not deleted: the registration of the sandbox's webhook endpoints and the request log of its test keys, whose rows expire after 30 days. Neither can be read once the sandbox is deleted. A delete that fails is safe to call again: it finishes what the first call started.
404 not_found: the id is not your own sandbox, or the workspace does not have thedeveloper_sandboxesfeature.429 quota_exceededwithRetry-After: 30and the message "Another sandbox is being reset or deleted. Try again in 30 seconds.": sandbox data is deleted one sandbox at a time. The test keys are already revoked; call the delete again to finish it.
Any member of the header workspace. A request made with a test key is refused. 403 permission_denied: a test key or another key held to a permission template, or a Client or Network member seat. 403 forbidden: no member is behind the credential.
curl -X DELETE "https://api.ken.so/v1/sandboxes/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentReset your sandbox to its seed data
/v1/sandboxes/{sandboxId}/resetsandboxes.reset- Permission
- Any workspace member except a Network member
- Rate limit
- 10 requests a day per user
developer_sandboxes feature on your workspace. Until it is on, calls answer 404.Deletes everything in the sandbox and seeds it again with the campaigns, contacts, sequences, threads and analytics a new sandbox starts with. Its test keys and webhook endpoints stay. Returns the sandbox with seed and the new lastResetAt. A reset that fails is safe to call again.
404 not_found: the id is not your own sandbox, or the workspace does not have thedeveloper_sandboxesfeature.429 quota_exceeded: you used your 10 sandbox creates and resets of the last 24 hours. They are counted per member, not per workspace.429 quota_exceededwithRetry-After: 30and the message "Another sandbox is being reset or deleted. Try again in 30 seconds.": sandbox data is deleted one sandbox at a time, for a reset and for a delete. A reset refused this way uses none of your creates and resets.
Any member of the header workspace. A request made with a test key is refused. 403 permission_denied: a test key or another key held to a permission template, or a Client or Network member seat. 403 forbidden: no member is behind the credential.
curl -X POST "https://api.ken.so/v1/sandboxes/812/reset" \
-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 Sandbox.
Show the 6 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Create another test key for your sandbox
/v1/sandboxes/{sandboxId}/test-keyssandboxes.create-test-key- Permission
- Any workspace member except a Network member
- Rate limit
- 50 requests a minute per API key
developer_sandboxes feature on your workspace. Until it is on, calls answer 404.Returns a new test key for the sandbox. Its secret (it starts kenso_test_) is returned once: store it now. It works only inside the sandbox, expires after 90 days, and is listed and revoked like any API key.
409 invalid_statewith the detail codetest_key_limit_reached: the sandbox already has 5 active test keys. Revoke one first.404 not_found: the id is not your own sandbox, or the workspace does not have thedeveloper_sandboxesfeature.
Any member of the header workspace. A request made with a test key is refused. 403 permission_denied: a test key or another key held to a permission template, or a Client or Network member seat. 403 forbidden: no member is behind the credential.
curl -X POST "https://api.ken.so/v1/sandboxes/812/test-keys" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 201
data is a SandboxTestKey.
Show the 4 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
More in Workspace and account:Your accountWorkspacesMembersPermission templatesAccess requestsCreditsCredit estimatesCredit ledgerCredit rate cardCredit savingsCredit savings rowsCredit spendWhite-label brandsCLI loginBug reportsAll resources