Sign in
sandboxes

POST /v1/orgs/:slug/sandboxes — create a new sandbox definition.

By default only persists the record (status = created). Pass ?start=true to also queue the job for orchestrator dispatch. Add wait_for=running to hold the response until the sandbox becomes usable or the bounded wait expires.

post/v1/orgs/{slug}/sandboxes

Path parameters

slugstring required

Organization slug

Query parameters

startboolean

If true, durably queue the sandbox for immediate orchestrator dispatch.

wait_forSandboxWaitFor — unresolved $ref

Optional lifecycle state to wait for after durable start admission.

wait_timeoutinteger nullable

Server-side wait budget in seconds; valid only with wait_for.

Request body

CreateSandboxRequest required— unresolved $ref

Response

Sandbox created

automatic_recovery_ends_atstring date-time nullable

When an explicit recovery choice becomes necessary.

created_atstring date-time required
ephemeralboolean required
idstring uuid required
last_failure_messagestring nullable

Human-readable reason for the last failure.

namestring required
org_idstring uuid required
slugstring required
started_atstring date-time nullable

Latest run's start time; null if the sandbox has never run.

status'created' | 'starting' | 'running' | 'temporarily_unavailable' | 'recovery_decision_required' | 'stopping' | 'stopped' | 'failed' required

Sandbox lifecycle status.

status_reason'scheduling' | 'insufficient_capacity'

Why a submitted sandbox is still waiting for placement on a worker. Only meaningful while status is starting.

stopped_atstring date-time nullable

Latest run's stop time; null while open or never run.

temporarily_unavailable_sincestring date-time nullable

When the current worker outage became user-visible.

Changes