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"

:

"ada@acme.example"

} }

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"

:

"ada@acme.example"

}}

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 email
whatsapp customer_message from , text , name? , reply_to? , phone_number?
whatsapp message_status message_id , status
whatsapp template_review template_id , status , reason?
whatsapp test_recipients add? (list), remove? (list), phone_number?
microsoft_teams add_person email , name , job_title?
microsoft_teams token email

POST /api/v1/sandboxes/p-7d21c4/apps/slack/actions/add_person

{

"handle"

:

"grace"

,

"name"

:

"Grace Hopper"

,

"email"

:

"grace@acme.example"

}

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"

:

"my-agent@0.3"

,

"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).

StateWeave action

writing tests

Limits

Record a verdict

Hand in a transcript

Sandboxes

Fill a sandbox

a new company

Get a sandbox

twin run

Apps and credentials

Tasks

Upload a task

Import a task

Faults in a task

Run your agent

Core concepts

cancel

a workflow's run

Start a run

worker