Create session

POST 
/v1/workspaces/:workspaceId/sessions

Creates a new session (remote development environment) and starts provisioning it.

Authentication

Accepts a Personal Access Token or a Workspace API Token (bitwat_…, created with Remote Dev Environments access). A PAT creates a personal session by default; set owner_type to workspace to create one owned by the workspace instead. A workspace token always creates workspace-owned sessions (owner_type may be omitted or workspace; user is rejected) — there is no user behind the token, so the session is visible to and manageable by every workspace member and listed under ?scope=SESSION_LIST_SCOPE_WORKSPACE. The token can then manage the sessions it created — read, list, update, terminate, restore, delete, sweep terminated ones, run commands, transfer files, take screenshots — and read the workspace's templates and machine catalog; it never sees a member's personal session.

Workspace-owned sessions

Use an existing template (template_id) or a bare stack_id + machine_type. Session inputs are given as plain values in session_inputs: every required input must be supplied that way, optional ones fall back to the template's default_value when omitted. Saved inputs are personal, so saved_input_id references and map_saved_to_session_inputs are rejected, and no saved SSH key or Claude credential is injected. ai_prompt is rejected for the same reason.

Out of CPUs

When the workspace is out of CPUs for the session's machine family, or at its machine limit, the call is refused with RESOURCE_EXHAUSTED (HTTP 429) rather than a bad request. The error carries a google.rpc.ErrorInfo detail with reason CPU_QUOTA_EXHAUSTED (metadata family, quota_vcpu, used_vcpu) or MACHINE_CONCURRENCY_EXHAUSTED (metadata machine_limit, active_machines), plus action (create or restore); the status message is written to be shown to a person as is.

Request

Responses

200

A successful response.