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.

Hosts

Method	Path	Description
GET	/v1/hosts	List hosts and their live utilization.
GET	/v1/hosts/{id}	Get 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.