Skip to main content
POST
Start a sandbox by name

Authorizations

Authorization
string
header
required

Organization API key (msb_…) - org-scoped programmatic access.

Path Parameters

name
string
required

Sandbox name (unique within the org)

Query Parameters

wait_for
null | enum<string>

Optional lifecycle state to wait for after durable start admission. Lifecycle state an opt-in create request may wait to observe.

Available options:
running
wait_timeout
integer<int64> | null

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

Required range: x >= 0

Response

Sandbox start admitted or requested wait completed

The API view of a [Sandbox]: an explicit allowlist of user-facing fields. Internal columns (registry selection, sync bookkeeping, resolved refs) never appear; the resolved spec surfaces only as the curated [SandboxSpecResponse].

created_at
string<date-time>
required
ephemeral
boolean
required
id
string<uuid>
required
name
string
required
org_id
string<uuid>
required
slug
string
required
status
enum<string>
required

Sandbox lifecycle status.

Available options:
created,
starting,
running,
stopping,
stopped,
failed
last_failure_message
string | null

Human-readable reason for the last failure.

spec
null | object

Curated projection of the resolved spec; absent until resolved.

started_at
string<date-time> | null

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

status_reason
null | enum<string>

Scheduler condition while status is starting.

Available options:
scheduling,
insufficient_capacity
stopped_at
string<date-time> | null

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