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.

Request

Responses

200

A successful response.