api
Reference
REST API
Everything sw and the Python SDK do goes through this API, so any language can do it too. Requests and responses are JSON unless an endpoint says otherwise.
Authentication
The API lives under your workspace's address, for example https://acme.app.stateweave.net . Send an API key as a bearer token on every request:
Request headers
GET
https://acme.app.stateweave.net/api/v1/me
Authorization
: Bearer sw_…
Content-Type
: application/json
Make and revoke keys in your workspace under Connect your agent (the key button). A key starts with sw_ , is shown once, and can do everything in its workspace: keep it out of code and logs. On a hosted workspace a key also stops working when the person who made it loses access to the workspace. A request whose Host is not the workspace's own name is refused ( 400 , unknown_host ).
Check a key
GET
/api/v1/me
The workspace's address, its name and the key's id and name.
Shell
curl
-s
https://acme.app.stateweave.net/api/v1/me
-H
"Authorization: Bearer $STATEWEAVE_API_KEY"
Response
{
"studio"
:
"https://acme.app.stateweave.net"
,
"name"
:
"acme"
,
"key"
: {
"id"
:
"k-3c19a2"
,
"name"
:
"my laptop"
}}
Errors
A refused request answers a 4xx or 5xx status and a JSON body with error , plus message , problems (every problem found, so you can fix them all at once), or both. An error about a run carries the run in run when there is one.
400 Bad Request
{
"error"
:
"invalid"
,
"problems"
: [
"agent: a label of up to 80 characters, e.g. my-agent@0.3"
,
"timeout: seconds between 60 and 86400"
] }
| Status | error | Meaning |
|---|---|---|
| 400 | invalid_json | The body is not JSON. |
| 400 | invalid | A field is missing or wrong; problems lists what to fix. |
| 400 | not_proven | An imported task failed a proof; proofs holds each one. |
| 400 | unknown_host | The request was not sent to the workspace's own name. |
| 401 | invalid_api_key | No key, a revoked key, or a key this workspace does not accept; hint says what to send. |
| 404 | not_found | No such sandbox, job, run, transcript or workflow. |
| 400 to 502 | run_error | A run could not do it; message says why. For example 404 no such test, 409 the run has ended ( run holds it) or the test needs a re-check, 429 too many runs going. |
| 400, 409, 500 | sandbox | The sandbox refused: an unknown app or mode (400), the wrong mode or state, such as connecting in test mode or generating into a sandbox that is not blank (409), or its apps would not start (500). |
| 409 | busy | The sandbox is re-checking or rewriting its tests, or has runs going, so its data or mode cannot change now. |
| 400, 404, 409 | action | A StateWeave action refused: a bad param or the app refused a step (400), no such app or action (404), test mode (409). |
| 410 | gone | A way that is no longer there, such as writing tests ; message says what to use instead. |
| 413 | too_large | A transcript over 20 MB. |
| 429 | rate_limited | A hosted workspace: too many requests with this key. Wait the Retry-After seconds. |
| 429 | limit | A hosted workspace's limit stopped it; message says which. See Limits . |
| 500 | not_started | An app would not start for an action. |
Sandboxes
A sandbox is the apps' data; its id is p-… . A new one is blank and in edit mode; you fill it through the apps' own APIs and StateWeave's actions, then switch it to test mode, which keeps a version that every run starts from. See Sandboxes and Fill a sandbox .
Older names. Sandboxes were called environments, and before that projects. Every /api/v1/sandboxes/{sandbox}… path below also works as /api/v1/environments/{sandbox}… and /api/v1/projects/{sandbox}… , and GET /api/v1/environments and GET /api/v1/projects list sandboxes too. The one difference is making one: POST /api/v1/sandboxes makes a blank sandbox, while POST /api/v1/environments and POST /api/v1/projects generate a company . Answers call a sandbox's id project .
List sandboxes
GET
/api/v1/sandboxes
{"projects": [sandbox, …]} , newest first, each as Get a sandbox shows it. No credentials.
Get a sandbox
GET
/api/v1/sandboxes/{sandbox}
Response
{
"id"
:
"p-7d21c4"
,
"title"
:
"Acme Support"
,
"description"
:
""
,
"apps"
: [
"slack"
,
"zendesk"
],
"created_at"
:
1793669077.4
,
"status"
:
"ready"
,
"error"
:
null
,
"company"
:
null
,
"steps"
: [],
"envs"
: {
"slack"
: {
"counts"
: {
"people"
:
3
,
"channels"
:
2
,
"messages"
:
14
,
"threads"
:
1
,
"DMs"
:
1
},
"summary"
:
"…"
,
"state"
:
"stopped"
} },
"kind"
:
"sandbox"
,
"mode"
:
"test"
,
"versions"
: [{
"n"
:
1
,
"at"
:
1793670012.8
,
"changes"
: {
"slack"
: {
"added"
:
16
,
"changed"
:
1
,
"removed"
:
0
}}}],
"owner"
: {
"name"
:
"Ada Lovelace"
,
"email"
:
} }
| Field | Description |
|---|---|
| kind | sandbox (made blank) or generated (made with a company). |
| mode | edit or test . |
| versions | Oldest first. Each {"n", "at", "changes"} : its number, when it was kept (Unix seconds), and per app the records added, changed and removed. |
| status | generating , ready , partial (some apps failed to generate) or failed , with error . |
| steps | A generation's steps, each {"key", "title", "status", "detail"} . |
| envs | Per app: counts (records of each kind), summary (the same in words) and state (whether the sandbox's own copy is up). |
| company | A generated company's name, else null . |
| owner | A blank sandbox's {"name", "email"} , else null . |
Make a blank sandbox
POST
/api/v1/sandboxes
| Field | Type | Description |
|---|---|---|
| name | string | Required. What to call it; the first 80 characters are kept. |
| apps | string[] | Required. App names: slack , gmail , google_calendar , google_sheets , google_drive , salesforce , shopify , zendesk , whatsapp , microsoft_teams , stripe , hubspot , github . |
| owner.name | string | The owner's name. Default Sandbox Owner . |
| owner.email | string | The owner's email address. Default owner@example.com . |
| time_zone | string | An IANA time zone name. Default UTC . |
Answers 201 with the sandbox: "kind": "sandbox" , "mode": "edit" , "status": "ready" , no versions. Each app holds only its account, the owner and the owner's token. 400 invalid without a name, or with an owner email that has no @ ; 400 sandbox with no apps or an unknown one.
Body
{
"name"
:
"Acme Support"
,
"apps"
: [
"slack"
,
"zendesk"
],
"owner"
: {
"name"
:
"Ada Lovelace"
,
"email"
:
}}
Connect
POST
/api/v1/sandboxes/{sandbox}/connect
Edit mode only. No body. Starts the sandbox's own apps and answers {"sandbox", "mode", "persona", "apps", "env"} : persona is the owner's handle; apps holds per app its base_url , endpoints , the owner's credentials and mcp (the MCP server they open, {"url", "headers"} , or null ); env holds the same as variables, named as for a twin run . What you write through these addresses is the sandbox's data. 409 in test mode; 500 when an app would not start. See Apps and credentials .
StateWeave's actions
GET
/api/v1/sandboxes/{sandbox}/actions
{"mode", "actions": {app: [{"name", "title", "about", "params": {name: {"type", "required", "about"}}}]}} : what StateWeave can do in each of the sandbox's apps that happens outside the real API.
POST
/api/v1/sandboxes/{sandbox}/apps/{app}/actions/{action}
Body: the action's params as an object. Edit mode only. Answers {"action", "app", "results"} , the app's answer to each step. Errors use "error": "action" : 400 for a missing, wrong or unknown param or when the app refused a step, 404 for an app the sandbox lacks or an action it has not, 409 in test mode.
| App | Action | Params ( ? : optional) |
|---|---|---|
| slack | add_person | handle , name , email |
| slack | token | handle |
| google_calendar | add_person | email , name , time_zone? |
| google_calendar | token | email , scopes? (list) |
| salesforce | token | username |
| zendesk | token | |
| customer_message | from , text , name? , reply_to? , phone_number? | |
| message_status | message_id , status | |
| template_review | template_id , status , reason? | |
| test_recipients | add? (list), remove? (list), phone_number? | |
| microsoft_teams | add_person | email , name , job_title? |
| microsoft_teams | token |
POST /api/v1/sandboxes/p-7d21c4/apps/slack/actions/add_person
{
"handle"
:
"grace"
,
"name"
:
"Grace Hopper"
,
"email"
:
}
Generate into a blank sandbox
POST
/api/v1/sandboxes/{sandbox}/generate
Body: {"description", "options"} , as for a new company . Replaces the blank sandbox's data with a generated company's and answers 202 with the sandbox, status generating ; read it until the status changes. The sandbox keeps its name. 400 invalid without a description or with bad options; 409 sandbox once it holds anything (a version, an earlier generation, or a change in edit mode) or while it generates; 409 busy ; 429 limit .
What changed in edit mode
GET
/api/v1/sandboxes/{sandbox}/changes
{"mode", "changes": {app: {"added", "changed", "removed"}}, "versions"} : per app what edit mode changed that is not in a version yet, only apps that changed. Empty in test mode.
Switch mode
POST
/api/v1/sandboxes/{sandbox}/mode
Body: {"mode": "edit"} or {"mode": "test"} . Switching to test stops the apps and, when anything changed since the last version, keeps what they hold as a new version; the tests of the apps that changed then need a re-check. Switching to edit starts the apps again from the latest version. Answers with the sandbox. 400 sandbox for another mode; 409 sandbox while it is generating or failed; 409 busy ; 500 sandbox when edit mode could not start.
Rename a sandbox
PATCH
/api/v1/sandboxes/{sandbox}
Body: {"name": "Acme support"} . Changes its name only and answers with the sandbox. 400 invalid without a name; 409 sandbox while it is generating.
Copy a sandbox
POST
/api/v1/sandboxes/{sandbox}/copy
Body (optional): {"name": "Acme refunds"} , by default "<name> copy" . Answers 201 with the new sandbox: what this one's apps hold now is its version 1 (no version when they hold only what the sandbox was made with), in the same mode, with copied_from naming the original. Earlier versions, tests and runs are not copied. 409 sandbox while it is generating or failed; 500 sandbox when a copy in edit mode could not start its apps (it is then in test mode on version 1).
Generated companies
Generate a company
POST
/api/v1/environments
Makes a new sandbox and generates a made-up company into it. POST /api/v1/projects does the same.
| Field | Type | Description |
|---|---|---|
| description | string | Required. The company and what the agent will be tested on. |
| apps | string[] | Required. App names, as for a blank sandbox. |
| options.company | string | The company's name; the first 80 characters are kept. |
| options.people | integer | Employees, 2 to 5,000. |
| options.weeks | integer | Weeks of history, 1 to 104. |
| options.content | string | auto (Claude when the workspace has it, else templates), llm (Claude only) or templates . Anything else counts as auto . |
Answers 201 with the new sandbox: status generating , "kind": "generated" , "mode": "test" , no versions. Read it with Get a sandbox until its status is ready , partial or failed ; steps show how far it got. 400 invalid for a missing field or a value out of range; 429 limit . See Fill a sandbox .
Body
{
"description"
:
"A 40-person outdoor gear shop; the agent answers order questions"
,
"apps"
: [
"shopify"
,
"gmail"
],
"options"
: {
"people"
:
40
,
"weeks"
:
8
}}
Tasks and tests
A task is a folder in Harbor's layout; a test is a task kept in your workspace, id t-… . See Tasks and Upload a task .
Import a task
POST
/api/v1/sandboxes/{sandbox}/tasks
| Field | Type | Description |
|---|---|---|
| files | object | Required. The task's files as {path: text} : instruction.md , task.toml , tests/checks.json and/or tests/verify.py , and optionally solution/solve.py . |
| check_only | boolean | Prove it, keep nothing. |
The task is proven on fresh copies of the sandbox's latest version: doing nothing must fail, and a reference solution, when there is one, must pass. Then it is kept as a test: 201 with {"test", "proofs", "kept": true} . With check_only nothing is kept: 200 , "test": null , "kept": false . test has id , project , title , prompt , kind , apps , answer_format , persona and "source": "upload" ; each proof is {"key", "title", "ok", "detail"} .
| Status | When |
|---|---|
| 400 invalid | The task cannot be read: problems lists every problem (a missing file, bad TOML or JSON, a check a task may not use, a stateweave_sandbox that names another sandbox). |
| 400 not_proven | A proof failed: proofs holds each one, the failed ones with what they found. |
| 409 invalid | The sandbox is not ready (generating or failed). |
| 429 limit | A hosted workspace's daily test limit (not counted with check_only ). |
Hosted workspaces. For now a hosted workspace refuses ( 400 , invalid ) a task that has tests/verify.py or solution/solve.py , with or without check_only . Judge it with tests/checks.json alone.
List tests
GET
/api/v1/tests?sandbox={sandbox}
The tests you can run, every sandbox's or one's. The query may also be named environment or project . Never a test's checks or reference solution. A test that needs a re-check is listed too; starting a run of it answers 409 until a re-check passes.
Response
{
"tests"
: [ {
"id"
:
"t-bde537"
,
"project"
:
"p-7d21c4"
,
"project_title"
:
"Acme Support"
,
"title"
:
"Reply to the refund question"
,
"prompt"
:
"A customer asked about a refund in #support. …"
,
"kind"
:
"action"
,
"apps"
: [
"slack"
],
"answer_format"
:
""
,
"persona"
: {
"name"
:
"Ada Lovelace"
,
"handle"
:
"owner"
,
"title"
:
"Owner"
},
"faults"
:
0
} ] }
faults is how many faults the test may inject.
Write tests: gone
POST
/api/v1/sandboxes/{sandbox}/tests
Tests are only uploaded. This path, and its /environments and /projects forms, answers 410 . Upload a task instead: see Import a task .
Response
{
"error"
:
"gone"
,
"message"
:
"the studio does not write tasks: upload one in Harbor's layout with sw task import PATH (or POST /api/v1/sandboxes/<id>/tasks)"
}
Get a job
GET
/api/v1/sandboxes/{sandbox}/jobs/{job}
A job ( j-… ) that wrote tests, from before tasks were only uploaded. It still answers: status ( running , done or failed with an error ) and items , each request's status , with test_id for a kept one.
Re-check tests
POST
/api/v1/sandboxes/{sandbox}/tests/recheck
Body: {"tests": [test ids]} , or nothing for all. Re-checks, in the background, the tests that need it because a new version changed their data. Answers {"rechecking": [test ids]} . A test that passes its re-check can be run again; one that fails still needs a re-check, marked with the checks that failed.
Fault presets
GET
/api/v1/sandboxes/{sandbox}/faults
{"presets": [{"id", "app", "kind", "title", "observed", "evidence"}]} : the faults the sandbox's tests may inject. observed is true when it was seen on the real service, false when carried over from another app's.
Fault targets
GET
/api/v1/sandboxes/{sandbox}/endpoints
Where faults can act: {"apps": {app: {"title", "kinds", "endpoints"}}, "kinds", "noise": {"defaults", "limits"}} . Each endpoint has an id , a label such as PUT /api/v2/tickets/{ticket_id} , a family , a class ( read , write or auth ) and the kinds that can happen there. noise gives random injection's defaults and allowed ranges. A task pins faults to these endpoints in its task.toml ; see Faults in a task .
Runs
A run is your agent's attempt on fresh copies of a sandbox's latest version; its id is r-… . See Run your agent , and Core concepts for the statuses.
Start a run
POST
/api/v1/runs
| Field | Type | Description |
|---|---|---|
| test | string | Required. The test's id. |
| sandbox | string | The sandbox's id, when the test id is in several. project and environment are the same field. |
| agent | string | The label runs are compared by, up to 80 characters. Default agent . |
| timeout | number | Seconds before it ends unfinished, 60 to 86,400. Default 1,800. |
| meta | object | Shown with the run, up to 4,000 characters as JSON. |
Answers 201 with the run once its apps are up. run_error : 404 for no such test, 400 for a test id in several sandboxes without sandbox , 409 when the test needs a re-check or its sandbox's apps are gone, 429 when the workspace has as many runs going as it allows, 500 when the apps would not start.
Response (shortened)
{
"id"
:
"r-aee3438d"
,
"project"
:
"p-7d21c4"
,
"test"
:
"t-bde537"
,
"test_version"
:
1
,
"test_title"
:
"Reply to the refund question"
,
"kind"
:
"action"
,
"agent"
:
,
"meta"
: {
"model"
:
"my-model"
},
"status"
:
"running"
,
"created_at"
:
1793669077.43
,
"expires_at"
:
1793670877.43
,
"timeout"
:
1800.0
,
"prompt"
:
"A customer asked about a refund in #support. …"
,
"answer_format"
:
""
,
"persona"
: {
"name"
:
"Ada Lovelace"
,
"handle"
:
"owner"
,
"title"
:
"Owner"
},
"url"
:
"https://acme.app.stateweave.net/\#/runs/r-aee3438d"
,
"attempt"
:
1
,
"apps"
: {
"slack"
: {
"base_url"
:
"https://…"
,
"endpoints"
: {
"web_api"
:
"https://…/api/"
,
"mcp"
:
"https://…/mcp"
},
"credentials"
: {…},
"mcp"
: {
"url"
:
"https://…/mcp"
,
"headers"
: {…}}}},
"env"
: {
"STATEWEAVE_SLACK_URL"
:
"https://…"
,
"STATEWEAVE_SLACK_MCP_URL"
:
"https://…/mcp"
,
"STATEWEAVE_SLACK_USER_TOKEN"
:
"xoxp-…"
} }
Get a run
GET
/api/v1/runs/{run}
The run as it stands. Every answer about a run has these fields:
| Field | Description |
|---|---|
| id , project | The run's id and its sandbox's id. |
| test , test_version , test_title | The test; null for a twin run. |
| kind | answer , action or twin . |
| prompt , answer_format , persona | What the agent is asked, the shape of its answer, whom it acts for. |
| agent , meta | The label and what you sent with it. |
| status | queued , starting , running , grading , passed , failed , timed_out , cancelled , interrupted , error or ended . |
| created_at , expires_at , finished_at , timeout | Unix seconds, and the time limit in seconds. |
| passed , reasons | The verdict once graded, and why. |
| answer | The answer handed in. |
| calls | Calls the agent made, once it has ended. |
| state | Once it has ended: per app {"added", "changed", "removed"} ( null for an app whose start is unknown); null when no end state was kept. |
| attempt , resets | The current attempt and how many resets there were. |
| transcript | {"format", "bytes", "at"} when one was handed in. |
| verdicts | Verdicts recorded with Record a verdict . |
| url | The run's page. |
| apps , env | Only while it runs: what to connect with. |
Finish a run
POST
/api/v1/runs/{run}/finish
| Field | Type | Description |
|---|---|---|
| answer | any | The agent's answer. Leave it out for an action test. |
| transcript | string or any | The agent's own record of the run, kept first as Hand in a transcript does; a JSON value is kept as JSON text. |
| transcript_format | string | Its form, e.g. claude-code-stream-json . Default: guessed. |
Grades the run on what the agent left in the apps, its answer and its requests, stops the apps and answers with the run as it ended: passed , failed , or error when the test's own judging failed. 409 run_error when the run had already ended ( run holds it) or for a twin run, which is not graded.
Body
{
"answer"
: {
"total_paid_usd"
:
349.10
,
"orders"
: [
"NG-1234"
,
"NG-1235"
]}}
Cancel a run
POST
/api/v1/runs/{run}/cancel
Gives the run up: its apps stop and it is not graded. Answers with the run, status cancelled ; a twin run ends as ended , keeping what its apps held. A queued run is cancelled before a worker takes it. 409 once it has ended.
Twin runs
A twin run is fresh copies of a sandbox's apps, from its latest version, with no test: something to develop against. Nothing grades it. It can be reset to how it started, and it ends when you stop it ( cancel ) or its time runs out.
Open a twin run
POST
/api/v1/runs
| Field | Type | Description |
|---|---|---|
| sandbox | string | Required, with no test . The sandbox whose apps to serve. project and environment are the same field. |
| apps | string[] | Which of its apps. Default: all. |
| ttl | number | Seconds it stays up, 60 to 86,400. Default 3,600. |
| agent | string | A label, up to 80 characters. Default coding-agent . |
| persona | string | The handle of the person the agent acts as. Default: the sandbox's first person (a blank sandbox's owner, owner ). |
| meta | object | Shown with the run, up to 4,000 characters as JSON. |
Answers 201 with the run: "kind": "twin" , "test": null , the persona, and apps and env as for a test run. run_error : 404 for no such sandbox, 409 when it has nothing to serve yet (generating or failed), 400 for an app it lacks or an unknown persona, 429 when the workspace has as many runs going as it allows or the key has 3 twin runs going.
env names each app's address STATEWEAVE_<APP>_URL , its MCP server STATEWEAVE_<APP>_MCP_URL when it has one, and each credential STATEWEAVE_<APP>_<KIND>_TOKEN , where KIND is what the credential's label says before the colon ( USER , BOT , APP , MCP , SETUP ). A kind that comes more than once adds the rest of the label. <APP> is the app's name in capitals, e.g. GOOGLE_CALENDAR .
Reset a twin run
POST
/api/v1/runs/{run}/reset
Body: {"apps": […]} , or nothing for all. Puts the apps back to how the run started, with the same credentials, and begins a new attempt: attempt goes up by one and the trace tells each call's attempt. Answers with the run. 409 for a test run (start another run of the test) or once it has ended; 400 for an app the run lacks.
Look at a run
These work on test runs and twin runs alike. Requests StateWeave sends to the apps for call and check are not your agent's: they are left out of the trace and of the grading.
What changed
GET
/api/v1/runs/{run}/changes
{"attempt", "changes": {app: {"added", "changed", "removed"}}} : how many records each app gained, changed and lost since the run started, or null for an app whose start is unknown. Worked out now while the run goes; as kept once it has ended. Only counts: to see what an app holds, ask it through its API with call or a request check.
The full trace
GET
/api/v1/runs/{run}/trace?attempt=N
Every call the agent made, with its whole request and response, as JSON lines ( application/x-ndjson ): first a line about the run, then one per call, then one per injected fault that acted. attempt keeps one attempt's calls.
Lines
{
"type"
:
"run"
,
"id"
:
"r-19dc0cec"
,
"status"
:
"running"
,
"attempts"
:
2
,
"calls"
:
4
,
"omitted"
:
0
} {
"type"
:
"call"
,
"app"
:
"slack"
,
"seq"
:
2
,
"at"
:
1793943988.7
,
"surface"
:
"webapi"
,
"method"
:
"chat.postMessage"
,
"http_method"
:
"POST"
,
"path"
:
"/api/chat.postMessage"
,
"query"
:
""
,
"ok"
:
true
,
"error"
:
null
,
"status"
:
200
,
"request"
:
"channel=C01&text=…"
,
"response"
:
"{\"ok\":true,…}"
,
"attempt"
:
1
} {
"type"
:
"fault"
,
"app"
:
"slack"
,
"name"
:
"…"
,
"kind"
:
"transient_auth"
,
"at"
:
1793943988.6
,
"method"
:
"POST"
,
"path"
:
"/api/chat.postMessage"
}
An ended run keeps up to 50 million characters of calls whole; omitted counts the calls past that.
Ask an app
POST
/api/v1/runs/{run}/call
| Field | Type | Description |
|---|---|---|
| app | string | Required. One of the run's apps. |
| method | string | GET , POST , PUT , PATCH , DELETE or HEAD . Default GET . |
| path | string | Required. The path on the app, e.g. /api/conversations.list . |
| query | object or string | Query parameters. |
| body | any | An object or array is sent as JSON, anything else as text. |
| headers | object | Headers to send. |
| credential | string | A credential's label, or its kind ( user , bot , …), sent as Authorization: Bearer unless headers has one. Shopify takes X-Shopify-Access-Token : put it in headers . |
Only while the run goes. Answers {"status", "headers", "body", "json"} ( json when the body is JSON; body is cut after 2,000,000 characters). 409 once the run has ended; 400 for an app or credential the run lacks; 502 when the app did not answer.
Check a run
POST
/api/v1/runs/{run}/check
Body: {"checks": […], "answer"?: …} , 1 to 50 checks. A task's tests/checks.json works as it is; pass your agent's answer for its answer checks. Each check is one of four kinds, has an optional name , and ends with expect , 1 to 20 assertions.
| Kind | Fields | Looks at |
|---|---|---|
| request | app , request : {"method", "path", "query"?, "body"?, "headers"?, "credential"?} , as ?, at ? | The app's answer to that request, through its public API. |
| answer | answer : {"path"?} | The answer you sent, or the part at path . |
| calls | calls : {"app"?, "http_method"?, "path"?, "path_matches"?, "status"?} | The requests the agent sent in the current attempt that match. |
request : without a credential or an Authorization header, the request is sent with the credential of the person as names (a handle such as owner , or a label such as user:grace ), else the owner's, else the agent's. "at": "start" asks a fresh copy of the sandbox's latest version, as it was before the agent, and works after the run has ended; "at": "end" , the default, asks the run's apps and needs the run to be going.
calls : path is exact, or a glob such as /api/v2/tickets/* ; path_matches is a regular expression searched in it. Each matching request is a record {"app", "http_method", "path", "query", "status", "ok", "request", "response"} , bodies as JSON where they were JSON or a form.
An assertion is {"path"?, "op", "value"?, "all"?} . The path picks values: a.b[0].c one value, [*] every item, ["a.b"] a key with a dot. In a request check it goes into the response's JSON, and $status , $body and $headers.name are the status, the text and a header. In a calls check it goes into each record, and with no path the assertion is about the records themselves. With several values one passing is enough; "all": true needs every one, as the negative operators always do.
Operators: equals , not_equals , contains , not_contains , matches (a regular expression), exists , not_exists , gt , gte , lt , lte , in (a list), and count_eq , count_gte , count_lte to count values or records.
Body
{
"checks"
: [ {
"name"
:
"the reply is in #support"
,
"app"
:
"slack"
,
"request"
: {
"method"
:
"GET"
,
"path"
:
"/api/conversations.history"
,
"query"
: {
"channel"
:
"C01"
}},
"expect"
: [{
"path"
:
"messages[*].text"
,
"op"
:
"contains"
,
"value"
:
"refund"
}]}, {
"name"
:
"posted once"
,
"calls"
: {
"app"
:
"slack"
,
"http_method"
:
"POST"
,
"path"
:
"/api/chat.postMessage"
},
"expect"
: [{
"op"
:
"count_eq"
,
"value"
:
1
}]}, {
"name"
:
"the answer names the order"
,
"answer"
: {
"path"
:
"orders"
},
"expect"
: [{
"op"
:
"contains"
,
"value"
:
"NG-1234"
}]} ],
"answer"
: {
"orders"
: [
"NG-1234"
]}}
Answers {"passed", "results": [{"index", "name", "ok", "detail", "actual"}]} ; actual is {"values", "count"} , up to five of the values found. 400 invalid with problems , each naming the check, when a check cannot be run as written. See Tasks for writing checks.
Hand in a transcript
POST
/api/v1/runs/{run}/transcript?format=F
The body is your agent's transcript as it is, in any format, up to 20 MB: Claude Code's stream-json , codex exec --json , your framework's messages, or plain text. It is kept as it came, labelled format (up to 60 letters, digits, . , - , + or _ ); without one, jsonl , json or text , as guessed. Another one replaces it. Works while the run goes and after it has ended. Answers with the run. 400 for an empty body or a bad format, 409 while the run is queued or starting, 413 over 20 MB.
GET
/api/v1/runs/{run}/transcript
The transcript as it came, with its format in the x-transcript-format header. 404 when there is none.
Record a verdict
POST
/api/v1/runs/{run}/verdict
| Field | Type | Description |
|---|---|---|
| verdict | string | Required. pass , fail or unsure . |
| judge | string | Who judged, e.g. claude-code , up to 80 characters. Default: the API key's name. |
| summary | string | Up to 4,000 characters. |
| criteria , reasons , evidence | arrays | Up to 100 items each: text, or objects such as {"app", "seq"} for a call. |
Your own judge's verdict on the run, for example your coding agent's after reading the trace. It is kept on the run's page beside the test's own result, which it does not change; a run keeps the latest 20. The whole verdict is 64,000 characters at most as JSON. Answers with the run.
Workers
A worker is your harness waiting for runs queued in the workspace: Run again on a run's page, or a workflow's run . sw worker is built on these.
Wait for a queued run
POST
/api/v1/workers/next
| Field | Type | Description |
|---|---|---|
| worker | string | Required. Your worker's own id, 4 to 40 letters, digits, - or _ , the same on every call. |
| agent | string | Required. The label its runs get, up to 80 characters. |
| meta | object | Shown with its runs. |
| timeout | number | Each run's time limit, 60 to 86,400. Default: the repeated run's. |
| wait | number | Seconds to wait for a run, 0 to 30. Default 25. |
Answers 201 with the oldest run queued for this worker or for any, started, as Start a run answers; or 204 when none came in time. Call it again at once: a worker counts as connected for a minute after its last call.
Stop a worker
POST
/api/v1/workers/{worker}/leave
The worker is no longer listed; runs queued for it wait for any other. Answers {"ok": true} .
Workflows
A workflow is one job your agent does and the tests that try it. It only groups tests, which may sit in several sandboxes; a test is in one workflow at most, so adding it to one takes it out of any other. Its id is w-… . A test is named {"project": sandbox id, "test": test id} .
List workflows
GET
/api/v1/workflows
{"workflows": [workflow, …]} , newest first. A workflow is {"id", "title", "description", "tests", "created_at", "updated_at", "source", "apps", "environments"} : apps and environments (each {"id", "title", "created_at"} ) are those its tests use; source is api or studio .
Make a workflow
POST
/api/v1/workflows
Body: {"title", "description"?, "tests"?} : a title of up to 120 characters, a description of up to 4,000, and up to 500 tests. Answers 201 with the workflow. 400 invalid for a bad field or a test that does not exist.
Body
{
"title"
:
"Refund replies"
,
"tests"
: [{
"project"
:
"p-7d21c4"
,
"test"
:
"t-bde537"
}]}
Get a workflow
GET
/api/v1/workflows/{workflow}
The workflow, as listed. 404 when there is none, here and below.
Change a workflow
PATCH
/api/v1/workflows/{workflow}
Body: {"title"?, "description"?, "add"?, "remove"?} , add and remove lists of tests. Answers with the workflow. 400 as for making one.
Delete a workflow
DELETE
/api/v1/workflows/{workflow}
Its tests stay. Answers {"ok": true} .
Run a workflow
POST
/api/v1/workflows/{workflow}/run
Body: {"worker"?, "tests"?} . Queues a run of each of the workflow's tests (or of those in tests ) for the worker named, or for any. Answers {"queued": [runs], "skipped": [{"project", "test", "why"}]} : 201 when at least one run was queued, 409 when none was. A queued run waits up to 10 minutes for a worker .
Limits
| What | Limit |
|---|---|
| Requests per API key | A hosted workspace: 50 at once, then 10 a second. Past that, 429 rate_limited with Retry-After: 1 . |
| Runs going at once | 8, or the workspace's own limit: test runs and twin runs together. |
| Twin runs per key | 3 at once. |
| Sandboxes on at once | A hosted workspace: 2 per person. On means its apps are up, asleep or starting, or it is generating. Turning on another one (start, edit mode, connect, an action, a copy in edit mode, generating) is 429 limit , naming the ones that are on: stop one first. |
| Idle apps | A hosted workspace: a sandbox's app nobody calls for 15 minutes goes to sleep, "state": "asleep" , on the same address with the same tokens. The next request wakes it and gets its answer once it is up: a moment, longer for an app with many recorded calls, which are replayed. A websocket is closed once with 1013 : connect again. Runs' apps don't sleep. |
| Run time | 60 to 86,400 seconds. Default 1,800 for a test run, 3,600 for a twin run. |
| Queued runs | 20 waiting at once; each waits 10 minutes for a worker, then is cancelled. |
| agent , meta | 80 characters; 4,000 characters as JSON. |
| Checks | 1 to 50 per request, 1 to 20 assertions each. |
| Answers of call | The body is cut after 2,000,000 characters. |
| Kept trace | 50 million characters of whole calls per ended run. |
| Transcript | 20 MB. |
| Verdicts | The latest 20 per run; 64,000 characters each as JSON. |
| Tasks | 50 files and 1 MB in all; instruction.md up to 20,000 characters; tests/verify.py and solution/solve.py up to 64,000 each. |
| Generated companies | 2 to 5,000 people; 1 to 104 weeks. |
| Workflows | 500 tests; a title of 120 characters, a description of 4,000. |
A hosted workspace may also set limits of its own, and answers 429 limit with a message saying which: generating once the sandboxes made that day reach its daily limit; the tests added in a day; the people a generated company may have; and Claude's monthly budget, after which nothing new that needs Claude starts (runs, re-checks and template-only generation still work).