API reference

Everything in qbox is driven by an HTTP API served by the control plane. The Python SDK and CLI wrap these endpoints — use them directly when you need a language without an SDK.

Base URL & authentication

All paths are under /v1 on your control-plane origin (same host as the dashboard). Authenticate machine clients with an API key as a bearer token (create one under API Keys in the dashboard):

export QBOX=https://qbox.your-company.internal
export TOKEN=qbox_...

curl -H "Authorization: Bearer $TOKEN" "$QBOX/v1/sandboxes"

The dashboard itself uses a session cookie; API keys are for programmatic access. GET /healthz is unauthenticated for liveness checks.

Sandboxes

Method	Path	Description
POST	/v1/sandboxes	Spawn a sandbox from a template.
GET	/v1/sandboxes	List sandboxes.
GET	/v1/sandboxes/{id}	Get one sandbox.
DELETE	/v1/sandboxes/{id}	Terminate a sandbox.
POST	/v1/sandboxes/{id}/timeout	Extend the auto-kill timeout (resets the timer).

A sandbox is auto-killed 5 minutes after spawn by default (e2b parity); pass timeoutSeconds on spawn to override, 0 to disable, or call the timeout endpoint / set_timeout to extend a running sandbox. | GET | /v1/sandboxes/{id}/logs | Fetch sandbox logs. |

# spawn
curl -X POST "$QBOX/v1/sandboxes" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"templateId":"tpl_python312"}'
# → { "id": "sb_7a3f", "status": "booting" }

Exec & processes

Method	Path	Description
POST	/v1/sandboxes/{id}/exec	Run a command, wait, return stdout/stderr/exit code.
POST	/v1/sandboxes/{id}/commands	Start a background process.
GET	/v1/sandboxes/{id}/commands	List processes.
GET	/v1/sandboxes/{id}/commands/{pid}	Process status.
GET	/v1/sandboxes/{id}/commands/{pid}/logs	Process logs.
DELETE	/v1/sandboxes/{id}/commands/{pid}	Kill a process.

curl -X POST "$QBOX/v1/sandboxes/sb_7a3f/exec" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"cmd":"python","args":["-c","print(1+1)"]}'
# → { "stdout": "2\n", "stderr": "", "exitCode": 0 }

Files

Method	Path	Description
GET	/v1/sandboxes/{id}/files?path=	List a directory.
GET	/v1/sandboxes/{id}/file?path=	Read a file.
PUT	/v1/sandboxes/{id}/file?path=	Write a file.
DELETE	/v1/sandboxes/{id}/file?path=	Remove a file.
GET	/v1/sandboxes/{id}/stat?path=	Stat a path.
GET	/v1/sandboxes/{id}/download?path=	Download a file (stream).
POST	/v1/sandboxes/{id}/files/mkdir	Create a directory.
POST	/v1/sandboxes/{id}/files/rename	Rename/move a path.

Code interpreter

Method	Path	Description
POST	/v1/sandboxes/{id}/code-execute	Run code in a stateful kernel.
GET	/v1/sandboxes/{id}/code-languages	List available languages.
GET	/v1/sandboxes/{id}/code-contexts	List kernel contexts.
POST	/v1/sandboxes/{id}/code-contexts	Create a context.
POST	/v1/sandboxes/{id}/code-contexts/{contextId}/restart	Restart a context.
DELETE	/v1/sandboxes/{id}/code-contexts/{contextId}	Remove a context.

Interactive shell (WebSocket)

GET /v1/sandboxes/{id}/shell upgrades to a WebSocket carrying an interactive PTY (for templates with SSH enabled). The dashboard Shell tab and the SDK’s shell() use this.

Templates

Method	Path	Description
GET	/v1/templates	List templates.
GET	/v1/templates/{id}	Get one template.
GET	/v1/templates/{id}/build-log	Fetch the build log.
POST	/v1/templates	Create + build a template from an OCI image.
POST	/v1/templates/from-git	Create + build a template from a public git repo (Dockerfile or railpack). Returns cacheHit, resolvedCommitSha, buildKey.
GET	/v1/templates?service=browser	Filter templates by a service capability (e.g. browser).

Browsers

Browser sessions run headful chromium with CDP exposed at wss://<id>.browser.<domain>/cdp. Scopes: browsers:read / browsers:write. Add ?wait=true to the create call to hold the session at starting until the live view is serving (by default it reports ready as soon as CDP is up).

Method	Path	Description
POST	/v1/browsers	Create a session from a browser-capable template (templateId required).
GET	/v1/browsers	List sessions (filter ?state=).
GET	/v1/browsers/{id}	Get one.
PATCH	/v1/browsers/{id}	Update keepAlive / visibility / allowedUsers.
DELETE	/v1/browsers/{id}	Terminate.
POST	/v1/browsers/{id}/signed-url	Mint a fresh signed connect + live-view URL.

Hosts

Method	Path	Description
GET	/v1/hosts	List hosts and their live utilization.
GET	/v1/hosts/{id}	Get one host.

Metrics

Time-series CPU, memory, disk, and network samples, queryable by range — the same data behind the dashboard charts.

Method	Path	Description
GET	/v1/sandboxes/{id}/metrics	Metrics for one sandbox.
GET	/v1/metrics/sandboxes	Recent samples for every running sandbox you can see.
GET	/v1/hosts/{id}/metrics	Metrics for one host.

API keys & audit

Method	Path	Description
GET	/v1/api-keys	List API keys.
POST	/v1/api-keys	Create a key (the secret is returned once).
POST	/v1/api-keys/{id}/revoke	Revoke a key.
GET	/v1/audit	Query the audit log.

Errors

Errors return a JSON body { "error": { "code": "...", "message": "..." } } with a matching HTTP status — 400 validation, 401/403 auth, 404 not found, 409 conflict, 422 policy/feature, 429 rate limited, 503 no capacity. Clients should retry only 429/503.