Skip to navigation
API ReferenceSandboxes

Create a sandbox

Beta
View as Markdown
Create a sandbox from an approved image. Returns while it is provisioning.

Authentication

AuthorizationBearer

Use Bearer <api-key>.

Headers

BCTRL-VersionenumOptional
Dated API version. Defaults to the release pinned when the API key was created.
Allowed values:
BCTRL-SpacestringOptional
Select one authorized Space by its opaque ID or unique name. Omission uses the operation default.
BCTRL-Subaccount-IdstringOptional
Optional effective subaccount context for organization API keys. Subaccount API keys are already scoped and cannot use this header to act as another subaccount.
Idempotency-KeystringOptional1-200 characters

Optional retry key for this billable operation. Reusing the same key with the same request replays its stable outcome; credential-bearing results may be freshly issued for the same principal. Reusing it with a different request returns 409.

Request

This endpoint expects an object.
auditobjectOptional
fromSnapshotstringOptional

Start as a fork of this snapshot (memory and disk), on the node that holds it. The image comes from the snapshot.

imagestringOptional<=200 characters

An approved image identifier such as bctrl-pi-stable, or any OCI image reference such as python:3.12 or ghcr.io/acme/tools@sha256:….

namestringOptional1-200 characters

Customer-facing resource name. 1–200 characters.

secretEnvobjectOptional

Environment variable names (letters, digits, underscore; not PATH, HOME, PROXY, BCTRL and other reserved names) to the Secret written for them.

snapshotScheduleobjectOptional
spaceIdstringOptional
Opaque resource ID or unique resource name in the selected Space or tenant.

Response headers

BCTRL-Request-IdstringOptional
Current request identifier, also echoed in errors.
BCTRL-VersionstringOptional
Negotiated dated API version.
RateLimit-Limitinteger

Evaluated policy limit; zero when no finite policy was evaluated.

RateLimit-Remaininginteger

Remaining policy budget; zero when no finite policy was evaluated.

RateLimit-Resetinteger

Seconds until reset; zero when no finite policy was evaluated.

Response

Accepted
auditobject
browserIdstring or null
capabilitiesobject
Capabilities qualified for this sandbox. false means not available.
conversationIdstring or null
createdAtdatetime
RFC 3339 timestamp with a UTC offset.
errorCodestring or null
idstring
Unique sandbox identifier generated by BCTRL.
imagestring
namestring or null
object"sandbox"
secretEnvobject or null

Secret substitution: references only, never values.

snapshotScheduleobject or null
spaceIdstring
Unique space identifier generated by BCTRL.
statusenum
updatedAtdatetime
RFC 3339 timestamp with a UTC offset.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error