sessions

Create or reuse a session

View as Markdown
Create a browser or sandbox session. Explicit `workspace` requests reuse the live VM for that workspace when one already exists, otherwise they spawn a new one. When `workspace` is omitted, free-tier accounts launch ephemerally and paid accounts resolve or auto-create the account default workspace for the requested session type. Set `ephemeral=true` to force a fresh non-persistent session without a workspace. Sandbox `image` is accepted only for ephemeral sessions; workspace-backed sessions inherit image from the workspace configuration.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
CreateSessionPersistentRequestDocobjectRequired
OpenAPI documentation schema for persistent session creation.
OR
CreateSessionEphemeralRequestDocobjectRequired
OpenAPI documentation schema for ephemeral session creation.

Response

Session created
created_atstring
endpointsobject
idstring
session_typestring
statusstring
active_connection_leasesinteger or null>=0

Active connection leases reported by the owning daemon (if available).

persistenceboolean or null
Whether this session's workspace is configured to persist after termination.
workspace_idstring or null
Durable workspace identity.

Errors

400
Bad Request Error