Skip to Content
Workspace and account

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.

Workspace and account6 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
sandboxIdpathinteger (int64)required

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.

List your sandboxes

GET/v1/sandboxessandboxes.list
Permission
Any workspace member except a Network member
Rate limit
12,000 requests a minute per API key
Needs the developer_sandboxes feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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

NameInTypeRequiredDescription
limitqueryinteger (int32)optionalItems 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.
cursorquerystringoptionalThe nextCursor of the previous page. Omit it for the first page.
Request
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

POST/v1/sandboxessandboxes.create
Permission
Any workspace member except a Network member
Rate limit
10 requests a day per user
Needs the developer_sandboxes feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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_state with the detail code sandbox_exists: you already have one. The detail message names its id; reset or delete it instead.
  • 404 not_found: the workspace does not have the developer_sandboxes feature.
  • 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.

Request
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

GET/v1/sandboxes/{sandboxId}sandboxes.get
Permission
Any workspace member except a Network member
Rate limit
12,000 requests a minute per API key
Needs the developer_sandboxes feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

404 not_found when the id is not your own sandbox, or the workspace does not have the developer_sandboxes feature. Any workspace member.

Request
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

DELETE/v1/sandboxes/{sandboxId}sandboxes.delete
Permission
Any workspace member except a Network member
Rate limit
4,800 requests a minute per API key
Needs the developer_sandboxes feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 the developer_sandboxes feature.
  • 429 quota_exceeded with Retry-After: 30 and 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.

Request
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

Response 204
HTTP/1.1 204 No Content

Reset your sandbox to its seed data

POST/v1/sandboxes/{sandboxId}/resetsandboxes.reset
Permission
Any workspace member except a Network member
Rate limit
10 requests a day per user
Needs the developer_sandboxes feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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 the developer_sandboxes feature.
  • 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_exceeded with Retry-After: 30 and 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.

Request
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

POST/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
Needs the developer_sandboxes feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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_state with the detail code test_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 the developer_sandboxes feature.

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.

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


On this page