The API

The Sandbox Router API lets you automate sandboxes, MCP servers, connectors, your users' logins and billing with an API key. It's a JSON API over HTTPS at https://api.sandboxrouter.io/v1, the sandboxrouter CLI (The CLI) maps its commands onto it one to one, and the TypeScript SDK (The TypeScript SDK) offers it as typed methods.

This guide covers authentication, the conventions every route follows, and the routes for each resource. The other guides explain what each resource does.

Authenticate

Create an API key

1. In the console, open Settings.

2. In the API keys card, enter a Key name, such as ci, and choose Create key. If you're an owner, you can also check Billing access, which lets the key read the balance and add funds.

3. Copy the key. It starts with ck_, and it isn't shown again.

Owners and operators can create keys; viewers can't. A key from the console doesn't expire: it works until you choose Revoke beside it. Keys, members and invitations are managed only in the console, never with an API key.

Send the key

Send the key as a bearer token:

export SANDBOXROUTER_API_KEY=<api-key>

curl https://api.sandboxrouter.io/v1/sandboxes \
  -H "Authorization: Bearer $SANDBOXROUTER_API_KEY"

A key belongs to one workspace, and every request it sends acts in that workspace: no path names a workspace. A sandbox, server or connector of another workspace, by ID or name, answers 404, as one that doesn't exist does. To work in another workspace, use a key created there.

Scopes

A key's scopes say which routes it may call. A key from the console has every scope but the two billing ones, and Billing access adds those.

Roles

A key can do what its scopes allow, within the role its creator has in the workspace now:

So if an operator who created a key becomes a viewer, the key can only read, and if they leave the workspace, the key gets 403. Adding, changing and removing connectors, and connecting or disconnecting their workspace accounts, needs an owner's key.

A revoked key, or a changed role, takes effect within a minute. Requests that grant access check the key at once instead: minting MCP client tokens, creating an MCP server, every change of a connector or its workspace account, and adding funds or changing auto-recharge.

Requests and responses

• Send request bodies as JSON, with Content-Type: application/json, except for files. A body larger than its route takes gets 413.

• Objects are flat: what you set and what Sandbox Router reports sit side by side. An unknown field is refused, naming it.

• A path's <sandbox> is a sandbox's ID, and <server> an MCP server's ID or name.

• Times are milliseconds since the Unix epoch. Money is in micro-USD: 1,000,000 is $1.

• A list answers { "<resource>": [...] }, and a paged one its nextCursor beside it: pass it back as ?cursor= for the next page. It's null on the last page.

• Deleting a sandbox or a snapshot answers { "id": "…", "deleted": true }. An MCP server's answer adds "sandboxDeleted", whether its sandbox went with it; a connector's adds how many users' connections and whether an account went with it; a file answers { "path": "…", "deleted": true }. Revoking a client token answers the token.

Errors

Every error has the same JSON body:

{ "error": { "code": "invalid_request", "message": "idleStopMinutes must be a whole number from 5 to 240", "field": "idleStopMinutes" } }

field names the request field a validation error is about; a nested one is dotted, as in sandbox.size. Other fields some errors carry sit inside error: a billing refusal's billingUrl, a 5xx's requestId.

Every 402 has a billingUrl: the console page where an owner adds funds or a card. See Billing and usage.

Request IDs

Every response has an x-sandboxrouter-request-id header that names the request. Sandbox Router logs everything the request did under that ID, and the audit log records it with each change. Quote it when you report a problem.

Rate limits

A request over a limit gets 429 with "code": "rate_limited" and a Retry-After header. Limits are counted at each edge location separately.

Idempotency keys

Requests that create something you mustn't create twice take an Idempotency-Key header of 8 to 128 letters, digits, _ and -. If you get no answer, or a 5xx, send the request again with the same key and body. If the first one went through, you get its result, and nothing is created twice.

Without the header, each request creates something new.

Sandboxes

See Sandboxes for every field and what it does.

Create a sandbox

curl https://api.sandboxrouter.io/v1/sandboxes \
  -H "Authorization: Bearer $SANDBOXROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: build-agent-0001" \
  -d '{
    "image": "default",
    "size": "l",
    "env": { "MODE": "ci" },
    "egress": ["api.github.com", "*.npmjs.org"],
    "labels": { "name": "build-agent", "team": "ci" },
    "connectors": ["github"]
  }'

{ "image": "default" } alone is a whole request. The request holds until the sandbox runs, and answers 201 Created with it:

{
  "id": "u-pjcusquzsv73qilmgdi6pmwfqhlyg7cn5xiehulebdf32cv42qsq",
  "image": "default",
  "command": null,
  "env": { "MODE": "ci" },
  "size": "l",
  "allocation": { "cpu": 1, "memoryGiB": 6, "diskGB": 12 },
  "egress": ["api.github.com", "*.npmjs.org"],
  "idleStopMinutes": 15,
  "labels": { "name": "build-agent", "team": "ci" },
  "providerLabels": null,
  "provider": "auto",
  "user": null,
  "connectors": ["github"],
  "providerId": "sb-4f9a0c1d2e3b",
  "currentProvider": "cloudflare",
  "state": "running",
  "stateMessage": null,
  "createdAt": 1791797400000,
  "startedAt": 1791797403000,
  "stoppedAt": null
}

A create that failed answers failed, with the reason in stateMessage. Sandbox Router sets no deadline of its own on it: how long to wait is yours to decide.

Sandbox routes

… is /v1/sandboxes/<sandbox>. A stopped sandbox stays stopped until …/start: an exec or a file transfer sent to it gets 409 not_running.

Execs

curl https://api.sandboxrouter.io/v1/sandboxes/<sandbox>/exec \
  -H "Authorization: Bearer $SANDBOXROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-tests-0001" \
  -d '{ "command": ["npm", "test"], "env": { "CI": "1" }, "workdir": "/workspace/app", "timeoutSeconds": 1800 }'

The request holds until the command ends and answers 200, or 202 at once with "detach": true:

{ "execId": "…", "state": "succeeded", "detach": false, "createdAt": 1791797400000, "endedAt": 1791797412000,
  "exitCode": 0, "signal": null, "stdout": "…", "stderr": "" }

state is running, succeeded, failed, timed_out, canceled or lost; stdout and stderr are null until it ends, then the whole output. A provider that can't take an exec's stdin, env, workdir or time limit refuses it with provider_feature_unavailable.

Logs

GET /v1/sandboxes/<sandbox>/logs answers { "entries": [{ "at", "stream", "message", "kind" }] }: every entry at or after ?since= (milliseconds or an ISO 8601 time), oldest first, kept for the sandbox's lifetime. Each is what Sandbox Router recorded of the sandbox (stream system): a state it reached, as its kind, with why. What its command writes is its provider's. With ?follow=true, the answer is newline-delimited JSON (application/x-ndjson): those entries, then each new one as it comes, for up to 10 minutes; follow on with since.

Metrics

GET /v1/sandboxes/<sandbox>/metrics answers { "samples": [{ "at", "cpuPct", "memUsedBytes", "memTotalBytes", "diskUsedBytes", "diskTotalBytes" }] }: the sandbox's provider's own measurements of its CPU (as a percentage of all its CPUs), memory and disk (in bytes), oldest first, from ?from= to ?to= (each in milliseconds; without from, from the sandbox's create, and without to, until now), as far back as the provider keeps them. A value the provider doesn't measure is null. A provider that keeps no metrics refuses them with provider_feature_unavailable, and a from after to (or a to before the sandbox's create, without from) is invalid_request.

Files

Each is the provider's own file operation on the running sandbox. <path> is the absolute path with each segment percent-encoded, as in /v1/sandboxes/<sandbox>/files/workspace/my%20file.txt; …/files/ is /, which can only be read. Paths under /proc, /sys and /dev are refused.

Snapshots

A snapshot is the provider's own. GET …/snapshots answers { "snapshots": [{ "id", "image", "memory", "createdAt" }] }, newest first. POST …/snapshots with {} has the provider take one of the running sandbox: { "snapshot" }. DELETE …/snapshots/<snapshot-id> deletes one.

MCP servers

curl https://api.sandboxrouter.io/v1/mcp-servers \
  -H "Authorization: Bearer $SANDBOXROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "search-mcp",
    "sandbox": { "image": "registry.caas.sh/<tenant-id>/search-mcp@sha256:…", "egress": ["api.search.example.com"] },
    "transport": { "http": { "port": 8080 } },
    "tokens": [{ "label": "laptop-claude", "allowedTools": ["search.query"] }]
  }'

The answer, 201, is the server: its id, its endpoint url (https://mcp.sandboxrouter.io/<id>), the sandboxId it runs in, transport, state, stats, and tokens, each minted token with its secret. See MCP servers for the endpoint, tokens and traces.

Connectors

<user> is your ID for the user, URL-encoded: user_123, or auth0%7Cabc for auth0|abc. The two lists take ?limit= (1 to 100, 50 by default) and ?after=, from the answer's next.

curl https://api.sandboxrouter.io/v1/users/user_123/connections \
  -H "Authorization: Bearer $SANDBOXROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connector": "linear", "returnUrl": "https://app.acme.com/settings" }'

The answer's connectUrl is the link to send the user. A sandbox created with "user": "user_123" then uses their accounts for the connectors its create names, and their logins in its browsers (see Logins). Codex (ChatGPT)'s users sign in with a code instead, from POST /v1/users/<user>/connections/<connector>/sign-in, made before a sandbox of theirs needs it; see Sign users in with a code.

curl https://api.sandboxrouter.io/v1/connectors \
  -H "Authorization: Bearer $SANDBOXROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "catalog": "openai" }'

curl https://api.sandboxrouter.io/v1/connectors/openai/account \
  -H "Authorization: Bearer $SANDBOXROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "method": "key", "key": "sk-..." }'

A sandbox gets a connector when its create names it ("connectors": ["openai"]). Sandboxes without a user then use the workspace's account. A connector's selector picks the workflows' sandboxes it reaches by their labels ({}, every one). See Connectors.

Billing

Billing routes need a key with Billing access, which only an owner can create. They work while the workspace is suspended.

curl "https://api.sandboxrouter.io/v1/billing/usage?month=2026-10" \
  -H "Authorization: Bearer $SANDBOXROUTER_API_KEY"

The usage report has a lines entry for each meter, with its quantity, unit and amountMicroUsd, the month's totalMicroUsd, a total for each UTC day in daily, and, while the month is under way, a projection for the whole month. The CSV has one row per UTC day and meter: day,meter,quantity,unit,rate_usd,amount_usd.

Adding funds charges the card on file and answers { "topUp": { … }, "url": null }; the balance goes up once the payment is confirmed. Without a card, or with "checkout": true, url is a Stripe Checkout page to finish the payment in. A declined card gets 402 with the failed topUp. See Billing and usage, and pricing for the rates.

Settings and the audit log

GET /v1/audit-log takes these filters, each at most once:

Each record has its time (at), actor, action, target, outcome, HTTP status, requestId and a short detail, never a secret, a token or a command's text. Records are kept for 365 days. An API key never sees records about API keys, members or invitations, sees billing records only with billing:read, and sees a user who made a change by ID, without their email.