Skip to main content
POST
/
api
/
v1
/
workspaces
/
{workspace_id}
/
sessions
Launch Workspace Session
curl --request POST \
  --url https://api.example.com/api/v1/workspaces/{workspace_id}/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "machine_id": "<string>",
  "user_session_id": "<string>",
  "metadata": {},
  "initial_prompt": "<string>",
  "worktree_name": "<string>",
  "session_settings": {
    "code": {
      "mode": "agent",
      "default_provider": "<string>",
      "providers": {
        "claude_code": {
          "model": "haiku"
        },
        "codex": {
          "model": "gpt-5.1-codex-max",
          "thinking": "low"
        }
      }
    },
    "voice": {
      "language": "<string>"
    }
  },
  "resume_session_id": "<string>",
  "agent_session_id": "<string>"
}
'
{
  "status": "<string>",
  "payload": {}
}

Authorizations

Authorization
string
header
required

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

Path Parameters

workspace_id
string
required

Body

application/json

Request body used to start a session for a workspace.

machine_id
string | null

Machine ID to launch the session on. If not provided, uses the workspace's default machine.

user_session_id
string | null

Existing user session to reuse

metadata
Metadata · object

Arbitrary metadata describing the launch

initial_prompt
string | null

Prompt delivered to the coding agent at startup

worktree_name
string | null

Name for the git worktree/branch to use for this session

session_settings
SessionSettings · object

Optional session settings overrides for this launch

resume_session_id
string | null

SDK session ID to resume from (e.g., from Claude CLI import)

agent_session_id
string | null

Existing agent session ID to connect to (e.g., from import)

Response

Successful Response

Daemon acknowledgement returned after a launch request.

status
string
required

Launch status (e.g., 'ok', 'error')

payload
Payload · object

Optional response payload with additional details