user_sessions

Create User Session Endpoint

Create a new user session container for the authenticated user.

Accepts either worktree_id (preferred) or workspace_id (deprecated). If workspace_id is provided, the main worktree for that workspace is used.

If start_sandbox is True and the worktree is REMOTE, the sandbox session will be started immediately after creating the user session.

post/api/v1/user-sessions

Request body

worktree_idstring nullable

Worktree identifier linked to this session (preferred)

workspace_idstring nullable

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

user_session_idstring nullable

Optional explicit user session id to reuse or create

namestring nullable

Optional human-readable session name

metadataobject nullable

Arbitrary key-value metadata for the session

start_sandboxboolean

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

initial_messagestring nullable

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

Successful Response

No recorded changes to this endpoint across all 1 revision of this API.