Skip to navigation
API ReferenceSandboxes

Open a terminal connection to a sandbox

Beta
View as Markdown

Open an interactive terminal (PTY) to a ready sandbox. Returns a WebSocket URL and a one-time ticket. Refused while a Task is using the sandbox.

Authentication

AuthorizationBearer

Use Bearer <api-key>.

Path parameters

sandboxIdstringRequired

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.
terminalobjectRequired

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

Created
createdAtdatetime
RFC 3339 timestamp with a UTC offset.
expiresAtdatetime
RFC 3339 timestamp with a UTC offset.
idstring
Unique sandboxConnection identifier generated by BCTRL.
object"sandbox_connection"
portinteger or null1-65535
The sandbox port, for a port preview.
protocolenum
Allowed values:
revokedAtdatetime or null
RFC 3339 timestamp with a UTC offset.
sandboxIdstring
Unique sandbox identifier generated by BCTRL.
subprotocol"bctrl.terminal.v1"
WebSocket subprotocol the client must offer.
ticketstring

One-time credential for opening the WebSocket, valid for one minute. Send it as Authorization: Bearer <ticket>, or from a browser as the subprotocol bctrl.ticket.<ticket> alongside bctrl.terminal.v1.

ticketExpiresAtdatetime
RFC 3339 timestamp with a UTC offset.
updatedAtdatetime
RFC 3339 timestamp with a UTC offset.
urlstringformat: "uri"
WebSocket URL to open. It carries no credential.

Errors

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