Skip to main content
POST
/
api
/
v1
/
user-sessions
Create User Session Endpoint
curl --request POST \
  --url https://api.example.com/api/v1/user-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "worktree_id": "<string>",
  "workspace_id": "<string>",
  "user_session_id": "<string>",
  "name": "<string>",
  "metadata": {},
  "start_sandbox": false,
  "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>"
    }
  },
  "initial_message": "<string>"
}
'
{
  "session": {
    "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "ACTIVE",
    "created_at": "2023-11-07T05:31:56Z",
    "kind": "user_session",
    "name": "<string>",
    "metadata": {},
    "settings": {
      "code": {
        "mode": "agent",
        "default_provider": "<string>",
        "providers": {
          "claude_code": {
            "model": "haiku"
          },
          "codex": {
            "model": "gpt-5.1-codex-max",
            "thinking": "low"
          }
        }
      },
      "voice": {
        "language": "<string>"
      }
    },
    "worktree_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "worktree_name": "<string>",
    "worktree_type": "LOCAL"
  },
  "agent_sessions": [
    {
      "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "session_type": "CODE",
      "connection_status": "CONNECTED",
      "work_status": "IDLE",
      "kind": "agent_session",
      "user_session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "parent_session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "daemon_version": "<string>",
      "metadata": {},
      "settings": {
        "code": {
          "mode": "agent",
          "default_provider": "<string>",
          "providers": {
            "claude_code": {
              "model": "haiku"
            },
            "codex": {
              "model": "gpt-5.1-codex-max",
              "thinking": "low"
            }
          }
        },
        "voice": {
          "language": "<string>"
        }
      }
    }
  ],
  "workspace": {
    "id": "<string>",
    "user_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "git_host": "<string>",
    "git_path": "<string>",
    "workspace_metadata": {},
    "workspace_config": {
      "git": {
        "remote": "origin",
        "base_ref": "main"
      },
      "sync": {
        "enabled": false
      },
      "remote_env": {
        "env": [
          {
            "key": "<string>",
            "value": "<string>"
          }
        ]
      },
      "setup": {
        "script": "<string>"
      }
    },
    "user_machine_paths": [
      {
        "user_machine_id": "<string>",
        "local_path": "<string>"
      }
    ]
  },
  "worktree": {
    "id": "<string>",
    "workspace_id": "<string>",
    "is_main": true,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "name": "<string>",
    "path": "<string>",
    "worktree_type": "LOCAL",
    "user_machine_path": {
      "id": "<string>",
      "machine_id": "<string>",
      "local_path": "<string>"
    },
    "managed_machine_id": "<string>",
    "last_heartbeat_at": "2023-11-07T05:31:56Z",
    "last_synced_checkpoint_id": "<string>",
    "checkpoint_restore_pending": false,
    "current_checkpoint_id": "<string>",
    "checkpoint_metadata": {}
  }
}

Authorizations

Authorization
string
header
required

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

Body

application/json

Payload for creating or reusing a user session container.

worktree_id
string | null

Worktree identifier linked to this session (preferred)

workspace_id
string | null

Deprecated: Use worktree_id instead. If worktree_id is not provided, the main worktree for this workspace will be used.

user_session_id
string | null

Optional explicit user session id to reuse or create

name
string | null

Optional human-readable session name

Maximum string length: 255
metadata
Metadata · object

Arbitrary key-value metadata for the session

start_sandbox
boolean
default:false

If True and worktree is REMOTE, start the sandbox session immediately

session_settings
SessionSettings · object

Initial session settings for this user session

initial_message
string | null

Initial message to queue for the agent. This message will be delivered as soon as the agent connects, eliminating the frontend waterfall delay.

Response

Successful Response

Aggregated user session data returned to clients.

session
UserSessionDescriptor · object
required

Core user session descriptor

agent_sessions
AgentSessionDescriptor · object[]

Agent sessions associated with this user session

workspace
WorkspaceDescriptor · object

Workspace linked to this session, if any

worktree
WorktreeDescriptor · object

Worktree linked to this session, if any