Sandbox API

Sandboxes

Sandboxes API endpoints

Sandboxes API endpoints

Every request needs a credential — see Authentication.

MethodPathSummary
GET/sandbox/sandboxes/v1List Sandboxes
POST/sandbox/sandboxes/v1Create Sandbox
POST/sandbox/sandboxes/v1/_reapReap Sandboxes
DELETE/sandbox/sandboxes/v1/{sandbox_id}Destroy Sandbox
GET/sandbox/sandboxes/v1/{sandbox_id}Get Sandbox
GET/sandbox/sandboxes/v1/{sandbox_id}/artifactsList Sandbox Artifacts
GET/sandbox/sandboxes/v1/{sandbox_id}/artifacts/{capture_id}Get Sandbox Artifact
POST/sandbox/sandboxes/v1/{sandbox_id}/captureCapture Sandbox
GET/sandbox/sandboxes/v1/{sandbox_id}/eventsSSE sandbox lifecycle events
POST/sandbox/sandboxes/v1/{sandbox_id}/execExec Sandbox
DELETE/sandbox/sandboxes/v1/{sandbox_id}/filesDelete File
GET/sandbox/sandboxes/v1/{sandbox_id}/filesGet File
PUT/sandbox/sandboxes/v1/{sandbox_id}/filesPut File
POST/sandbox/sandboxes/v1/{sandbox_id}/startStart Sandbox
POST/sandbox/sandboxes/v1/{sandbox_id}/stopStop Sandbox
POST/sandbox/sandboxes/v1/{sandbox_id}/verifyVerify Sandbox
GET/sandbox/sandboxes/v1/{sandbox_id}/viewerMint viewer URL or proxy Selkies UI
POST/sandbox/sandboxes/v1/{sandbox_id}/viewer/startStart Viewer
POST/sandbox/sandboxes/v1/{sandbox_id}/viewer/stopStop Viewer

Common headers

Accepted on every endpoint on this page.

NameInTypeRequiredDescription
x-correlation-idheaderstringnoEnd-to-end correlation id for this eval run. When set, the gateway and downstream services honor it verbatim in logs, Cloud Trace span attributes, async job payloads, and Langfuse trace.id. When omitted, the gateway generates a ULID and echoes it on the response.
X-Sandbox-Project-Idheaderstring | nullnoProject to bill and rate-limit this request against. Validated against the credential: a project-scoped token may only name its own project, and gets 403 otherwise. Defaults to the token's project when omitted.
X-Sandbox-Tenant-Idheaderstring | nullnoTenant for this request. Must match the credential's tenant when the credential carries one.

Endpoints

List Sandboxes

GET /sandbox/sandboxes/v1

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Create Sandbox

POST /sandbox/sandboxes/v1

Request body

application/json, required — CreateSandboxRequest

FieldTypeRequiredDescription
profilestringnoDefault: "sandboxes-default".
sourceobject | nullno
autostop_secnumber | nullno
ttl_secnumber | nullno
linked_job_idstring | nullno

Responses

StatusDescriptionBody
201Successful Responseany
422Validation ErrorHTTPValidationError

Reap Sandboxes

POST /sandbox/sandboxes/v1/_reap

Operator hook: stop/destroy idle sandboxes for this scope.

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Destroy Sandbox

DELETE /sandbox/sandboxes/v1/{sandbox_id}

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes

Responses

StatusDescriptionBody
204Successful Response—
422Validation ErrorHTTPValidationError

Get Sandbox

GET /sandbox/sandboxes/v1/{sandbox_id}

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

List Sandbox Artifacts

GET /sandbox/sandboxes/v1/{sandbox_id}/artifacts

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes
kindquerystring | nullno
limitqueryintegerno

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Get Sandbox Artifact

GET /sandbox/sandboxes/v1/{sandbox_id}/artifacts/{capture_id}

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes
capture_idpathstringyes

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Capture Sandbox

POST /sandbox/sandboxes/v1/{sandbox_id}/capture

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

SSE sandbox lifecycle events

GET /sandbox/sandboxes/v1/{sandbox_id}/events

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes
Last-Event-IDheaderstring | nullno

Responses

StatusDescriptionBody
200Successful Responseany
422Validation ErrorHTTPValidationError

Exec Sandbox

POST /sandbox/sandboxes/v1/{sandbox_id}/exec

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes

Request body

application/json, required — ExecRequest

FieldTypeRequiredDescription
commandstring[]yes
cwdstring | nullno
timeout_secnumber | nullno
envobject | nullno

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Delete File

DELETE /sandbox/sandboxes/v1/{sandbox_id}/files

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes
pathquerystringyes

Responses

StatusDescriptionBody
204Successful Response—
422Validation ErrorHTTPValidationError

Get File

GET /sandbox/sandboxes/v1/{sandbox_id}/files

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes
pathquerystringyes

Responses

StatusDescriptionBody
200Successful Responseany
422Validation ErrorHTTPValidationError

Put File

PUT /sandbox/sandboxes/v1/{sandbox_id}/files

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes
pathquerystringyes

Request body

application/json, required

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Start Sandbox

POST /sandbox/sandboxes/v1/{sandbox_id}/start

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Stop Sandbox

POST /sandbox/sandboxes/v1/{sandbox_id}/stop

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Verify Sandbox

POST /sandbox/sandboxes/v1/{sandbox_id}/verify

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes

Request body

application/json, required — VerifyRequest

FieldTypeRequiredDescription
require_verifier_evidencebooleannoDefault: false.

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Mint viewer URL or proxy Selkies UI

GET /sandbox/sandboxes/v1/{sandbox_id}/viewer

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes

Responses

StatusDescriptionBody
200Successful Responseany
422Validation ErrorHTTPValidationError

Start Viewer

POST /sandbox/sandboxes/v1/{sandbox_id}/viewer/start

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Stop Viewer

POST /sandbox/sandboxes/v1/{sandbox_id}/viewer/stop

Parameters

NameInTypeRequiredDescription
sandbox_idpathstringyes

Responses

StatusDescriptionBody
200Successful Responseobject
422Validation ErrorHTTPValidationError

Schemas

The object shapes referenced above.

CreateSandboxRequest

FieldTypeRequiredDescription
profilestringnoDefault: "sandboxes-default".
sourceobject | nullno
autostop_secnumber | nullno
ttl_secnumber | nullno
linked_job_idstring | nullno

ExecRequest

FieldTypeRequiredDescription
commandstring[]yes
cwdstring | nullno
timeout_secnumber | nullno
envobject | nullno

HTTPValidationError

FieldTypeRequiredDescription
detailValidationError[]no

ValidationError

FieldTypeRequiredDescription
locstring | integer[]yes
msgstringyes
typestringyes
inputanyno
ctxobjectno

VerifyRequest

FieldTypeRequiredDescription
require_verifier_evidencebooleannoDefault: false.

Machine-readable spec: OpenAPI YAML.

CodeEdit

Code execution without LLM

Admin

Credential plane administration

On this page

Common headersEndpointsList SandboxesResponsesCreate SandboxRequest bodyResponsesReap SandboxesResponsesDestroy SandboxParametersResponsesGet SandboxParametersResponsesList Sandbox ArtifactsParametersResponsesGet Sandbox ArtifactParametersResponsesCapture SandboxParametersResponsesSSE sandbox lifecycle eventsParametersResponsesExec SandboxParametersRequest bodyResponsesDelete FileParametersResponsesGet FileParametersResponsesPut FileParametersRequest bodyResponsesStart SandboxParametersResponsesStop SandboxParametersResponsesVerify SandboxParametersRequest bodyResponsesMint viewer URL or proxy Selkies UIParametersResponsesStart ViewerParametersResponsesStop ViewerParametersResponsesSchemasCreateSandboxRequestExecRequestHTTPValidationErrorValidationErrorVerifyRequest