Create a runtime or session
Create a browser runtime. Ephemeral runtimes (profile omitted or false) are single-session: by default they start in the same call and the response includes a `connection` with the run-scoped connect endpoint; pass start:false to defer startup (for example, to mint a share view first), then POST /start. They archive when their run finishes and never restart. Profile-backed runtimes (profile true) retain browser identity, remain reusable, and are created stopped by default; pass start:true for one-call create-and-start. Omit spaceId to use the caller's default space.
Authentication
AuthorizationBearer
Use Bearer <api-key>.
Headers
BCTRL-Subaccount-Id
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-Key
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.
config
metadata
name
profile
recording
spaceId
start
type
Response
Created
activeRunId
createdAt
RFC 3339 timestamp with a UTC offset.
id
Unique runtime identifier generated by BCTRL.
name
profile
spaceId
Unique space identifier generated by BCTRL.
status
type
updatedAt
RFC 3339 timestamp with a UTC offset.
archivedAt
RFC 3339 timestamp with a UTC offset.
config
connection
lastActivityAt
RFC 3339 timestamp with a UTC offset.
metadata
needsInput
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