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.
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Payload for creating or reusing a user session container.
Worktree identifier linked to this session (preferred)
Deprecated: Use worktree_id instead. If worktree_id is not provided, the main worktree for this workspace will be used.
Optional explicit user session id to reuse or create
Optional human-readable session name
255Arbitrary key-value metadata for the session
If True and worktree is REMOTE, start the sandbox session immediately
Initial session settings for this user session
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
Aggregated user session data returned to clients.
Core user session descriptor
Agent sessions associated with this user session
Workspace linked to this session, if any
Worktree linked to this session, if any