{ "openapi": "3.1.0", "info": { "title": "Omnara API", "description": "UNSTABLE -- This API is under active development. Endpoints, request/response shapes, and authentication requirements may change without notice. Do not build production integrations against these endpoints without contacting the Omnara team first.", "version": "0.1.0-unstable" }, "paths": { "/api/v1/auth/pat": { "get": { "tags": [ "auth" ], "summary": "List Pats", "description": "List PATs for the current user.", "operationId": "list_pats_api_v1_auth_pat_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PatSummary" }, "type": "array", "title": "Response List Pats Api V1 Auth Pat Get" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" }, "post": { "tags": [ "auth" ], "summary": "Create Pat", "description": "Issue a new personal access token for the current user.", "operationId": "create_pat_api_v1_auth_pat_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePatResponse" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/auth/pat/{pat_id}": { "delete": { "tags": [ "auth" ], "summary": "Delete Pat", "description": "Delete a PAT owned by the current user.", "operationId": "delete_pat_api_v1_auth_pat__pat_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "pat_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Pat Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/auth/sync-user": { "post": { "tags": [ "auth" ], "summary": "Sync User", "description": "Sync a user from Supabase to the local database.\n\nVerifies the requesting user matches the target, then updates the\ndisplay name if it has changed.", "operationId": "sync_user_api_v1_auth_sync_user_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncUserRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/auth/session": { "get": { "tags": [ "auth" ], "summary": "Get Session", "description": "Get the current session info for the authenticated user.\n\nReturns the user profile if authenticated, otherwise 401.", "operationId": "get_session_api_v1_auth_session_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/auth/me": { "get": { "tags": [ "auth" ], "summary": "Get Current User Profile", "description": "Get the authenticated user's profile.", "operationId": "get_current_user_profile_api_v1_auth_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfile" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" }, "delete": { "tags": [ "auth" ], "summary": "Delete User Account", "description": "Delete the current user's account and all associated data.\n\nRemoves the user from the database (including Stripe subscription\ncancellation) and then from Supabase auth. Returns 207 if the\ndatabase deletion succeeds but the Supabase deletion fails.", "operationId": "delete_user_account_api_v1_auth_me_delete", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" }, "patch": { "tags": [ "auth" ], "summary": "Update Current User Profile", "description": "Update the authenticated user's profile (e.g., display name).", "operationId": "update_current_user_profile_api_v1_auth_me_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfile" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/relay/register": { "post": { "tags": [ "relay" ], "summary": "Register Relay Instance", "description": "Register a relay client and return a short-lived relay token.\n\nThe relay token is used to authenticate the client's WebSocket\nconnection to the session relay channel.", "operationId": "register_relay_instance_api_v1_relay_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayRegisterRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayRegisterResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/relay/refresh": { "post": { "tags": [ "relay" ], "summary": "Refresh Relay Token", "description": "Refresh an expiring relay token and return a new one.\n\nValidates the existing token, verifies ownership, and issues\na replacement token with the same session and client kind.", "operationId": "refresh_relay_token_api_v1_relay_refresh_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayRefreshRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayRefreshResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/user/settings": { "get": { "tags": [ "user-settings" ], "summary": "Get Full Settings", "description": "Retrieve the current user's full settings.\n\nReturns the complete user settings object including notification preferences\n(mobile push notification mode, email and SMS notification settings,\nphone number, and notification email address) and any other user-level\nconfiguration.", "operationId": "get_full_settings_api_v1_user_settings_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSettings" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" }, "patch": { "tags": [ "user-settings" ], "summary": "Update User Settings", "description": "Partially update the current user's settings.\n\nAccepts optional fields to modify across all user settings, including\nnotification preferences such as mobile notification mode, email and SMS\ntoggles, phone number, and notification email. Validates phone numbers\nagainst E.164 format and ensures a phone number is present when SMS\nnotifications are enabled.", "operationId": "update_user_settings_api_v1_user_settings_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSettingsUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSettings" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/user-sessions": { "post": { "tags": [ "user_sessions" ], "summary": "Create User Session Endpoint", "description": "Create a new user session container for the authenticated user.\n\nAccepts either worktree_id (preferred) or workspace_id (deprecated).\nIf workspace_id is provided, the main worktree for that workspace is used.\n\nIf start_sandbox is True and the worktree is REMOTE, the sandbox session\nwill be started immediately after creating the user session.", "operationId": "create_user_session_endpoint_api_v1_user_sessions_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserSessionRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSessionSummary" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/user-sessions/{user_session_id}": { "get": { "tags": [ "user_sessions" ], "summary": "Get User Session Detail", "description": "Get details of a specific user session.\n\nReturns 404 if the session is not found or has been deleted.", "operationId": "get_user_session_detail_api_v1_user_sessions__user_session_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSessionSummary" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" }, "patch": { "tags": [ "user_sessions" ], "summary": "Update User Session", "description": "Update a user session (e.g., rename).\n\nReturns 404 if the session is not found or has been deleted.", "operationId": "update_user_session_api_v1_user_sessions__user_session_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserSessionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSessionDescriptor" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" }, "delete": { "tags": [ "user_sessions" ], "summary": "Delete User Session", "description": "Soft delete a user session by setting its status to DELETED.\n\nAfter the database delete completes, a best-effort RPC is sent to the\ndaemon to terminate any running session process. The delete always\nsucceeds regardless of daemon state.\n\nArgs:\n delete_worktree: If true, also delete the git worktree associated\n with this session on the user's machine.\n\nReturns:\n 204 No Content on success\n 404 if session not found or already deleted", "operationId": "delete_user_session_api_v1_user_sessions__user_session_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Session Id" } }, { "name": "delete_worktree", "in": "query", "required": false, "schema": { "type": "boolean", "description": "If true, also delete the git worktree associated with this session.", "default": false, "title": "Delete Worktree" }, "description": "If true, also delete the git worktree associated with this session." } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/user-sessions/{user_session_id}/restart": { "post": { "tags": [ "user_sessions" ], "summary": "Restart User Session", "description": "Stop a local session process and resume it, even if currently offline.", "operationId": "restart_user_session_api_v1_user_sessions__user_session_id__restart_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Session Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/user-sessions/{user_session_id}/stop": { "post": { "tags": [ "user_sessions" ], "summary": "Stop User Session", "description": "Stop a local session process without resuming it.", "operationId": "stop_user_session_api_v1_user_sessions__user_session_id__stop_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Session Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/user-sessions/{user_session_id}/agent-sessions/{agent_session_id}": { "get": { "tags": [ "user_sessions" ], "summary": "Get Agent Session Detail", "description": "Get a specific agent session with its child sessions.", "operationId": "get_agent_session_detail_api_v1_user_sessions__user_session_id__agent_sessions__agent_session_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Session Id" } }, { "name": "agent_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionDetail" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/user-sessions/{user_session_id}/agent-sessions/{agent_session_id}/messages": { "get": { "tags": [ "user_sessions" ], "summary": "Get Agent Session Messages", "description": "Retrieve paginated messages for an agent session.\n\nSupports cursor-based pagination using before_id or after_id\n(mutually exclusive). Messages are returned in chronological order.", "operationId": "get_agent_session_messages_api_v1_user_sessions__user_session_id__agent_sessions__agent_session_id__messages_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Session Id" } }, { "name": "agent_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Session Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum number of messages to return.", "default": 50, "title": "Limit" }, "description": "Maximum number of messages to return." }, { "name": "before_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return messages created strictly before this message id.", "title": "Before Id" }, "description": "Return messages created strictly before this message id." }, { "name": "after_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return messages created strictly after this message id.", "title": "After Id" }, "description": "Return messages created strictly after this message id." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagePageResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/user-sessions/{user_session_id}/agent-sessions/{agent_session_id}/mark-read": { "post": { "tags": [ "user_sessions" ], "summary": "Mark Agent Session Read", "description": "Mark an agent session as read for the current user.\n\nRead/unread is tracked server-side on agent_sessions.last_read_at and compared\nagainst agent_sessions.last_unread_event_at.", "operationId": "mark_agent_session_read_api_v1_user_sessions__user_session_id__agent_sessions__agent_session_id__mark_read_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Session Id" } }, { "name": "agent_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Session Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/user-sessions/{user_session_id}/agent-sessions/{agent_session_id}/messages/{message_id}": { "delete": { "tags": [ "user_sessions" ], "summary": "Cancel Queued Message", "description": "Cancel a pending message in the queue before it's delivered to the AI.\n\nOnly pending messages (delivered_at IS NULL) can be canceled.\nReturns 204 on success, 404 if message not found or already processed.", "operationId": "cancel_queued_message_api_v1_user_sessions__user_session_id__agent_sessions__agent_session_id__messages__message_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "user_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Session Id" } }, { "name": "agent_session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Session Id" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Message Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/user-sessions/import-claude-session": { "post": { "tags": [ "user_sessions" ], "summary": "Import Claude Session", "description": "Import messages from a Claude CLI session into a new Omnara session.\n\nThis creates:\n1. A new user_session linked to the workspace's main worktree\n2. A new agent_session for the imported messages\n3. All messages from the Claude CLI session\n\nThe agent_session_id can then be used as the resume_session_id when\nstarting the SDK to resume from the imported session.", "operationId": "import_claude_session_api_v1_user_sessions_import_claude_session_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportClaudeSessionRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportClaudeSessionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/machines/register": { "post": { "tags": [ "machines" ], "summary": "Register Machine", "description": "Register a new daemon machine or re-register an existing one.\n\nCreates the machine record if it does not already exist. Returns a\nshort-lived machine token that the daemon uses to authenticate its\nWebSocket connection.", "operationId": "register_machine_api_v1_machines_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineRegisterRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineRegisterResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/machines": { "get": { "tags": [ "machines" ], "summary": "List Machines", "description": "List all machines registered by the authenticated user, ordered by most recently updated.", "operationId": "list_machines_api_v1_machines_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineListResponse" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/workspaces/ensure": { "post": { "tags": [ "workspaces" ], "summary": "Ensure Workspace", "description": "Create or update a workspace and link it to a machine.\n\nThis endpoint:\n1. Finds or creates a workspace (by machine+path)\n2. Creates/updates the machine-workspace link with the local path\n3. Ensures a main worktree exists with the machine reference", "operationId": "ensure_workspace_api_v1_workspaces_ensure_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceEnsureRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDescriptor" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sessions": { "post": { "tags": [ "workspaces" ], "summary": "Launch Workspace Session", "description": "Launch a daemon-backed coding session for the given workspace.", "operationId": "launch_workspace_session_api_v1_workspaces__workspace_id__sessions_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSessionLaunchRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSessionLaunchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/config": { "patch": { "tags": [ "workspaces" ], "summary": "Update Workspace Config", "description": "Update workspace configuration (git, sync, remote_env, and setup settings).", "operationId": "update_workspace_config_api_v1_workspaces__workspace_id__config_patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceConfigUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDescriptor" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/by-path": { "get": { "tags": [ "workspaces" ], "summary": "Get Workspace By Path", "description": "Get workspace by machine ID and local path.", "operationId": "get_workspace_by_path_api_v1_workspaces_by_path_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "machine_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Machine Id" } }, { "name": "local_path", "in": "query", "required": true, "schema": { "type": "string", "title": "Local Path" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDescriptor" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}": { "get": { "tags": [ "workspaces" ], "summary": "Get Workspace By Id", "description": "Get workspace by ID.", "operationId": "get_workspace_by_id_api_v1_workspaces__workspace_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDescriptor" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" }, "delete": { "tags": [ "workspaces" ], "summary": "Delete Workspace", "description": "Soft delete a workspace and its associated sessions.", "operationId": "delete_workspace_api_v1_workspaces__workspace_id__delete", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/upload-url": { "post": { "tags": [ "workspaces" ], "summary": "Get Sync Upload Url", "description": "Generate a presigned URL for uploading a sync bundle.\n\nBundle types:\n- base_ref: Full bundle of base branch (keyed by SHA)\n- head_ref: Incremental from base to HEAD (keyed by SHA)\n- checkpoint: Incremental from HEAD to checkpoint (keyed by ID)", "operationId": "get_sync_upload_url_api_v1_workspaces__workspace_id__sync_upload_url_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncUploadUrlRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncUploadUrlResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/download-url": { "post": { "tags": [ "workspaces" ], "summary": "Get Sync Download Url", "description": "Generate a presigned URL for downloading a sync bundle.", "operationId": "get_sync_download_url_api_v1_workspaces__workspace_id__sync_download_url_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncDownloadUrlRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncDownloadUrlResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/base-ref-exists": { "post": { "tags": [ "workspaces" ], "summary": "Check Base Ref Bundle Exists", "description": "Check if a base-ref bundle exists (for deduplication by SHA).", "operationId": "check_base_ref_bundle_exists_api_v1_workspaces__workspace_id__sync_base_ref_exists_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseRefExistsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseRefExistsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/head-ref-exists": { "post": { "tags": [ "workspaces" ], "summary": "Check Head Ref Bundle Exists", "description": "Check if a head-ref bundle exists (for deduplication by SHA).", "operationId": "check_head_ref_bundle_exists_api_v1_workspaces__workspace_id__sync_head_ref_exists_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadRefExistsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadRefExistsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/checkpoints": { "get": { "tags": [ "workspaces" ], "summary": "List Sync Checkpoints", "description": "List all bundles available in remote storage.", "operationId": "list_sync_checkpoints_api_v1_workspaces__workspace_id__sync_checkpoints_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncCheckpointListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/state": { "patch": { "tags": [ "workspaces" ], "summary": "Update Sync State", "description": "Update sync state after successful upload.", "operationId": "update_sync_state_api_v1_workspaces__workspace_id__sync_state_patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStateUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" }, "get": { "tags": [ "workspaces" ], "summary": "Get Sync State", "description": "Get current sync state for a workspace.", "operationId": "get_sync_state_api_v1_workspaces__workspace_id__sync_state_get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncStateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/checkpoint-upload-url": { "post": { "tags": [ "workspaces" ], "summary": "Get Checkpoint Upload Urls", "description": "Get presigned upload URLs for checkpoint sync (two-tier).\n\nReturns:\n- head_url: Presigned URL for HEAD bundle (null if already exists)\n- checkpoint_url: Presigned URL for checkpoint bundle (always provided)\n\nThe HEAD bundle is keyed by SHA for deduplication - if it already exists,\nhead_url will be null to skip the upload.", "operationId": "get_checkpoint_upload_urls_api_v1_workspaces__workspace_id__sync_checkpoint_upload_url_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointUploadUrlRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointUploadUrlResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/base-ref-upload-url": { "post": { "tags": [ "workspaces" ], "summary": "Get Base Ref Upload Url", "description": "Get presigned upload URL for base ref bundle.\n\nReturns:\n- upload_url: Presigned URL (null if bundle already exists)\n- already_exists: Whether the bundle already exists\n\nThe base ref bundle is keyed by SHA for deduplication.", "operationId": "get_base_ref_upload_url_api_v1_workspaces__workspace_id__sync_base_ref_upload_url_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseRefUploadUrlRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseRefUploadUrlResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/checkpoint-status": { "patch": { "tags": [ "workspaces" ], "summary": "Update Checkpoint Sync Status", "description": "Update checkpoint sync status on the worktree.\n\nCalled by the daemon after successfully uploading a checkpoint.\n\nUpdates:\n1. Sets last_synced_checkpoint_id on the worktree that owns this checkpoint\n2. Always updates workspace sync_state.synced_checkpoints\n\nWorktree lookup strategy:\n1. First try matching current_checkpoint_id (fast path for quick syncs)\n2. If not found (race condition: user created new checkpoint during sync),\n fall back to the single worktree if only one exists\n\nThe last_synced_checkpoint_id field tracks the last successfully synced\ncheckpoint. This may differ from current_checkpoint_id if:\n- The user created new checkpoints while sync was in progress\n- A sync upload failed for a more recent checkpoint\n\nThis allows us to always have a known-good checkpoint to fall back to.", "operationId": "update_checkpoint_sync_status_api_v1_workspaces__workspace_id__sync_checkpoint_status_patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointSyncStatusUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Update Checkpoint Sync Status Api V1 Workspaces Workspace Id Sync Checkpoint Status Patch" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/init-worktree-checkpoint": { "post": { "tags": [ "workspaces" ], "summary": "Init Worktree Checkpoint", "description": "Initialize a worktree's checkpoint state to base ref.\n\nCalled when sync is enabled at session start to set the initial checkpoint\nstate. This indicates the worktree starts from a clean base ref state,\nwhich is considered \"synced\" because the base ref bundle has already been\nuploaded via `workspace sync --enable`.\n\nThis allows migration/resume from the base ref checkpoint.", "operationId": "init_worktree_checkpoint_api_v1_workspaces__workspace_id__sync_init_worktree_checkpoint_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitWorktreeCheckpointRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitWorktreeCheckpointResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/checkpoint-download-url": { "post": { "tags": [ "workspaces" ], "summary": "Get Checkpoint Download Urls", "description": "Get presigned download URLs for checkpoint restoration.\n\nUsed when restoring a checkpoint that doesn't exist locally (e.g., after\ncloning a repo on a new machine). Returns URLs for both the HEAD bundle\n(if the checkpoint was based on a HEAD commit) and the checkpoint bundle.\n\nSupports two checkpoint formats:\n1. Regular checkpoints: Returns HEAD bundle URL + checkpoint bundle URL\n2. Base checkpoints (base:{sha}): Returns only base_ref bundle URL as checkpoint_bundle_url\n\nThe checkpoint metadata is looked up from the database (stored when the\ncheckpoint was originally synced). If head_sha is present, both bundles\nare needed; otherwise only the checkpoint bundle.", "operationId": "get_checkpoint_download_urls_api_v1_workspaces__workspace_id__sync_checkpoint_download_url_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointDownloadUrlRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointDownloadUrlResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/workspaces/{workspace_id}/sync/enable": { "post": { "tags": [ "workspaces" ], "summary": "Enable Workspace Sync", "description": "Enable sync for a workspace.\n\nThis endpoint is designed to be called from the web UI. It:\n1. Sends an RPC request to the user's machine to enable sync\n2. The machine daemon will upload the base ref bundle\n3. The machine daemon will sync all worktree checkpoints\n4. The machine daemon will update the workspace config to enable sync\n\nReturns immediately after sending the RPC request. The actual sync\noperation happens asynchronously on the machine.\n\nArgs:\n workspace_id: The workspace to enable sync for\n machine_id: Optional machine ID to target. If not provided, will use\n the first online machine that has this workspace.", "operationId": "enable_workspace_sync_api_v1_workspaces__workspace_id__sync_enable_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } }, { "name": "machine_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Machine Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Enable Workspace Sync Api V1 Workspaces Workspace Id Sync Enable Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/worktrees/{worktree_id}": { "get": { "tags": [ "worktrees" ], "summary": "Get Worktree Endpoint", "description": "Get a worktree by ID.", "operationId": "get_worktree_endpoint_api_v1_worktrees__worktree_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "worktree_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Worktree Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorktreeDescriptor" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/worktrees/workspace/{workspace_id}": { "get": { "tags": [ "worktrees" ], "summary": "List Workspace Worktrees", "description": "List all worktrees for a workspace.", "operationId": "list_workspace_worktrees_api_v1_worktrees_workspace__workspace_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorktreeDescriptor" }, "title": "Response List Workspace Worktrees Api V1 Worktrees Workspace Workspace Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/worktrees/ensure": { "post": { "tags": [ "worktrees" ], "summary": "Ensure Worktree Endpoint", "description": "Ensure a worktree exists, creating if needed.\n\nIf name is \"main\", returns the main worktree.\nOtherwise, creates/returns a named worktree.", "operationId": "ensure_worktree_endpoint_api_v1_worktrees_ensure_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorktreeEnsureRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorktreeDescriptor" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ], "x-stability": "unstable" } }, "/api/v1/worktrees/session/{session_id}": { "patch": { "tags": [ "worktrees" ], "summary": "Set User Session Worktree", "description": "Set the worktree for a user session.", "operationId": "set_user_session_worktree_api_v1_worktrees_session__session_id__patch", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorktreeSetRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorktreeDescriptor" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } }, "/api/v1/worktrees/{worktree_id}/migrate": { "post": { "tags": [ "worktrees" ], "summary": "Migrate Worktree", "description": "Migrate a worktree to a different machine type (LOCAL or REMOTE).\n\nFor LOCAL: Requires target_machine_id pointing to a user's machine.\nFor REMOTE: Creates a managed machine (sandbox), provisions the workspace,\n and starts sessions in the sandbox.\n\nThe migration process:\n1. Stops any running sessions on the current machine (if migrating from local)\n2. Updates the worktree's machine association\n3. For REMOTE: Provisions sandbox workspace and starts sessions in background\n\nSpecial case: When source='base_ref' and worktree_name is provided, creates a\nnew worktree with that name as REMOTE from base_ref, ignoring the worktree_id.", "operationId": "migrate_worktree_api_v1_worktrees__worktree_id__migrate_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "worktree_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Worktree Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorktreeMigrateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorktreeMigrateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-stability": "unstable" } } }, "components": { "schemas": { "AgentCompleteContent": { "properties": { "type": { "type": "string", "const": "agent_complete", "title": "Type", "description": "Content type discriminator", "default": "agent_complete" }, "success": { "type": "boolean", "title": "Success", "description": "Whether the agent turn completed successfully" }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Ms", "description": "Duration of the agent turn in milliseconds" }, "cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cost Usd", "description": "Estimated cost of the turn in USD" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Optional completion message" }, "checkpoint": { "anyOf": [ { "$ref": "#/components/schemas/CheckpointInfo" }, { "type": "null" } ], "description": "Checkpoint created at the end of the turn" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata about the completion" } }, "additionalProperties": false, "type": "object", "required": [ "success" ], "title": "AgentCompleteContent", "description": "Completion marker for an agent session turn." }, "AgentConnectionStatus": { "type": "string", "enum": [ "CONNECTED", "DISCONNECTED" ], "title": "AgentConnectionStatus" }, "AgentProgressContent": { "properties": { "type": { "type": "string", "const": "agent_progress", "title": "Type", "description": "Content type discriminator", "default": "agent_progress" }, "status": { "type": "string", "title": "Status", "description": "Current progress status label" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail", "description": "Optional detailed progress description" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Optional structured progress metadata" } }, "additionalProperties": false, "type": "object", "required": [ "status" ], "title": "AgentProgressContent", "description": "Incremental progress emitted by an agent session." }, "AgentSessionDescriptor-Output": { "properties": { "kind": { "type": "string", "const": "agent_session", "title": "Kind", "description": "Descriptor type discriminator", "default": "agent_session" }, "session_id": { "type": "string", "format": "uuid", "title": "Session Id", "description": "Unique agent session identifier" }, "user_session_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "User Session Id", "description": "Parent user session identifier" }, "parent_session_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Session Id", "description": "Parent agent session identifier (for sub-agents)" }, "session_type": { "$ref": "#/components/schemas/AgentSessionType", "description": "Type of agent session" }, "connection_status": { "$ref": "#/components/schemas/AgentConnectionStatus", "description": "Current WebSocket connection status" }, "work_status": { "$ref": "#/components/schemas/AgentWorkStatus", "description": "Current work/processing status" }, "daemon_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Daemon Version", "description": "Version of the daemon running this session" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Arbitrary agent session metadata" }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/SessionSettings-Output" }, { "type": "null" } ], "description": "Session settings for this agent session" } }, "additionalProperties": false, "type": "object", "required": [ "session_id", "session_type", "connection_status", "work_status" ], "title": "AgentSessionDescriptor", "description": "Representation of an agent-scoped session." }, "AgentSessionDetail": { "properties": { "session": { "$ref": "#/components/schemas/AgentSessionDescriptor-Output", "description": "The agent session descriptor" }, "child_sessions": { "items": { "$ref": "#/components/schemas/AgentSessionDescriptor-Output" }, "type": "array", "title": "Child Sessions", "description": "Child agent sessions spawned from this session" } }, "type": "object", "required": [ "session" ], "title": "AgentSessionDetail", "description": "Detailed agent session with child sessions." }, "AgentSessionType": { "type": "string", "enum": [ "CODE", "VOICE" ], "title": "AgentSessionType" }, "AgentWorkStatus": { "type": "string", "enum": [ "IDLE", "WORKING", "COMPLETED" ], "title": "AgentWorkStatus" }, "BaseRefExistsRequest": { "properties": { "sha": { "type": "string", "title": "Sha" } }, "additionalProperties": false, "type": "object", "required": [ "sha" ], "title": "BaseRefExistsRequest", "description": "Request to check if a base-ref bundle exists." }, "BaseRefExistsResponse": { "properties": { "exists": { "type": "boolean", "title": "Exists" }, "storage_key": { "type": "string", "title": "Storage Key" } }, "additionalProperties": false, "type": "object", "required": [ "exists", "storage_key" ], "title": "BaseRefExistsResponse", "description": "Response indicating if base-ref bundle exists." }, "BaseRefUploadUrlRequest": { "properties": { "sha": { "type": "string", "title": "Sha" } }, "additionalProperties": false, "type": "object", "required": [ "sha" ], "title": "BaseRefUploadUrlRequest", "description": "Request for a presigned upload URL for base ref bundle." }, "BaseRefUploadUrlResponse": { "properties": { "upload_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Upload Url" }, "storage_key": { "type": "string", "title": "Storage Key" }, "already_exists": { "type": "boolean", "title": "Already Exists" } }, "additionalProperties": false, "type": "object", "required": [ "upload_url", "storage_key", "already_exists" ], "title": "BaseRefUploadUrlResponse", "description": "Response containing presigned upload URL for base ref.\n\nupload_url is null if the bundle already exists (deduplicated)." }, "CheckpointDownloadUrlRequest": { "properties": { "checkpoint_id": { "type": "string", "title": "Checkpoint Id" } }, "additionalProperties": false, "type": "object", "required": [ "checkpoint_id" ], "title": "CheckpointDownloadUrlRequest", "description": "Request for presigned download URLs to restore a checkpoint.\n\nThe checkpoint_id is used to look up the checkpoint metadata from the\ndatabase (worktree.checkpoint_metadata), which contains the head_sha\nneeded to download the HEAD bundle." }, "CheckpointDownloadUrlResponse": { "properties": { "head_bundle_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Head Bundle Url" }, "checkpoint_bundle_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checkpoint Bundle Url" }, "head_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Head Sha" }, "exists": { "type": "boolean", "title": "Exists" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error" } }, "additionalProperties": false, "type": "object", "required": [ "head_bundle_url", "checkpoint_bundle_url", "head_sha", "exists" ], "title": "CheckpointDownloadUrlResponse", "description": "Response containing presigned download URLs for checkpoint restoration.\n\nTo restore a checkpoint remotely:\n1. Download and apply head_bundle_url (if provided) - contains commits up to HEAD\n2. Download and apply checkpoint_bundle_url - contains incremental checkpoint data\n\nFor checkpoints created in empty repos (no HEAD), head_bundle_url will be null." }, "CheckpointInfo": { "properties": { "checkpoint_id": { "type": "string", "title": "Checkpoint Id", "description": "Unique checkpoint identifier" }, "additions": { "type": "integer", "title": "Additions", "description": "Number of lines added since last checkpoint" }, "deletions": { "type": "integer", "title": "Deletions", "description": "Number of lines deleted since last checkpoint" }, "files_changed": { "type": "integer", "title": "Files Changed", "description": "Number of files modified in this checkpoint" }, "synced": { "type": "boolean", "title": "Synced", "description": "Whether checkpoint was uploaded to remote storage", "default": false }, "head_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Head Sha", "description": "HEAD commit SHA at checkpoint time (for remote restore)" } }, "additionalProperties": false, "type": "object", "required": [ "checkpoint_id", "additions", "deletions", "files_changed" ], "title": "CheckpointInfo", "description": "Information about a code checkpoint." }, "CheckpointSyncStatusUpdateRequest": { "properties": { "checkpoint_id": { "type": "string", "title": "Checkpoint Id" }, "synced": { "type": "boolean", "title": "Synced" } }, "additionalProperties": false, "type": "object", "required": [ "checkpoint_id", "synced" ], "title": "CheckpointSyncStatusUpdateRequest", "description": "Request to update checkpoint sync status on a worktree." }, "CheckpointUploadUrlRequest": { "properties": { "head_sha": { "type": "string", "title": "Head Sha" }, "checkpoint_id": { "type": "string", "title": "Checkpoint Id" } }, "additionalProperties": false, "type": "object", "required": [ "head_sha", "checkpoint_id" ], "title": "CheckpointUploadUrlRequest", "description": "Request for presigned upload URLs for a checkpoint.\n\nReturns 1-2 URLs:\n- head_url: Only if HEAD bundle doesn't exist yet (deduplicated by SHA)\n- checkpoint_url: Always returned for the checkpoint bundle" }, "CheckpointUploadUrlResponse": { "properties": { "head_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Head Url" }, "checkpoint_url": { "type": "string", "title": "Checkpoint Url" }, "head_storage_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Head Storage Key" }, "checkpoint_storage_key": { "type": "string", "title": "Checkpoint Storage Key" } }, "additionalProperties": false, "type": "object", "required": [ "head_url", "checkpoint_url", "head_storage_key", "checkpoint_storage_key" ], "title": "CheckpointUploadUrlResponse", "description": "Response containing presigned upload URLs for checkpoint sync.\n\nhead_url is null if the HEAD bundle already exists (deduplicated).\ncheckpoint_url is always provided." }, "ClaudeCodeSettings": { "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "haiku", "sonnet", "opus", "opus[1m]" ] }, { "type": "null" } ], "title": "Model" } }, "additionalProperties": false, "type": "object", "title": "ClaudeCodeSettings", "description": "Claude-specific settings for the code agent." }, "CodeAgentProviders": { "properties": { "claude_code": { "anyOf": [ { "$ref": "#/components/schemas/ClaudeCodeSettings" }, { "type": "null" } ] }, "codex": { "anyOf": [ { "$ref": "#/components/schemas/CodexSettings" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "CodeAgentProviders", "description": "Provider-specific code agent settings keyed by provider name." }, "CodeAgentSettings-Input": { "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "agent", "orchestrator" ] }, { "type": "null" } ], "title": "Mode" }, "default_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Provider" }, "providers": { "$ref": "#/components/schemas/CodeAgentProviders" } }, "additionalProperties": true, "type": "object", "title": "CodeAgentSettings", "description": "Settings for the code agent across providers." }, "CodeAgentSettings-Output": { "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "agent", "orchestrator" ] }, { "type": "null" } ], "title": "Mode" }, "default_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Provider" }, "providers": { "$ref": "#/components/schemas/CodeAgentProviders" } }, "additionalProperties": true, "type": "object", "title": "CodeAgentSettings", "description": "Settings for the code agent across providers." }, "CodexSettings": { "properties": { "model": { "anyOf": [ { "type": "string", "enum": [ "gpt-5.1-codex-max", "gpt-5.1-codex-mini", "gpt-5.1-codex", "gpt-5.2", "gpt-5.2-codex", "gpt-5.3-codex-spark", "gpt-5.3-codex" ] }, { "type": "null" } ], "title": "Model" }, "thinking": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high", "xhigh" ] }, { "type": "null" } ], "title": "Thinking" } }, "additionalProperties": false, "type": "object", "title": "CodexSettings", "description": "Codex-specific settings for the code agent." }, "CompactionCompletedContent": { "properties": { "type": { "type": "string", "const": "compaction_completed", "title": "Type", "description": "Content type discriminator", "default": "compaction_completed" }, "trigger": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trigger", "description": "What triggered the compaction (e.g., 'manual', 'auto')" }, "pre_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Pre Tokens", "description": "Number of tokens in context before compaction" } }, "additionalProperties": false, "type": "object", "title": "CompactionCompletedContent", "description": "System message indicating context compaction has completed.\n\nEmitted when the agent finishes compressing its context window.\nIncludes metadata about the compaction operation." }, "CompactionStartedContent": { "properties": { "type": { "type": "string", "const": "compaction_started", "title": "Type", "description": "Content type discriminator", "default": "compaction_started" } }, "additionalProperties": false, "type": "object", "title": "CompactionStartedContent", "description": "System message indicating context compaction has started.\n\nEmitted when the agent begins compressing its context window to free space." }, "ContextUsageContent": { "properties": { "type": { "type": "string", "const": "context_usage", "title": "Type", "description": "Content type discriminator", "default": "context_usage" }, "input_tokens": { "type": "integer", "title": "Input Tokens", "description": "Number of input tokens used" }, "output_tokens": { "type": "integer", "title": "Output Tokens", "description": "Number of output tokens generated" }, "cache_read_input_tokens": { "type": "integer", "title": "Cache Read Input Tokens", "description": "Input tokens served from cache" }, "cache_creation_input_tokens": { "type": "integer", "title": "Cache Creation Input Tokens", "description": "Input tokens used to populate cache" }, "context_window": { "type": "integer", "title": "Context Window", "description": "Maximum context window size in tokens" }, "cost_usd": { "type": "number", "title": "Cost Usd", "description": "Estimated cost in USD for this turn" }, "model": { "type": "string", "title": "Model", "description": "Model name used for the turn" } }, "additionalProperties": false, "type": "object", "required": [ "input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "context_window", "cost_usd", "model" ], "title": "ContextUsageContent", "description": "Context usage information from SDK result.\n\nEmitted after each turn completes with token usage data.\nStreamed envelopes are ephemeral, but a snapshot is stored in session metadata\nso the UI can hydrate on reconnect/resume." }, "CreatePatResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the PAT." }, "created_at": { "type": "string", "title": "Created At", "description": "ISO-8601 timestamp when the PAT was created." }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Used At", "description": "ISO-8601 timestamp when the PAT was last used, if ever." }, "token": { "type": "string", "title": "Token", "description": "The raw PAT value. Only returned at creation time." } }, "type": "object", "required": [ "id", "created_at", "token" ], "title": "CreatePatResponse", "description": "Response returned when a new PAT is created, including the token value shown only once." }, "CreateUserSessionRequest": { "properties": { "worktree_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Worktree Id", "description": "Worktree identifier linked to this session (preferred)" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id", "description": "Deprecated: Use worktree_id instead. If worktree_id is not provided, the main worktree for this workspace will be used." }, "user_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Session Id", "description": "Optional explicit user session id to reuse or create" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "Optional human-readable session name" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Arbitrary key-value metadata for the session" }, "start_sandbox": { "type": "boolean", "title": "Start Sandbox", "description": "If True and worktree is REMOTE, start the sandbox session immediately", "default": false }, "session_settings": { "anyOf": [ { "$ref": "#/components/schemas/SessionSettings-Input" }, { "type": "null" } ], "description": "Initial session settings for this user session" }, "initial_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Message", "description": "Initial message to queue for the agent. This message will be delivered as soon as the agent connects, eliminating the frontend waterfall delay." } }, "type": "object", "title": "CreateUserSessionRequest", "description": "Payload for creating or reusing a user session container." }, "DefaultWorktreeMode": { "type": "string", "enum": [ "new_worktree", "repo_root" ], "title": "DefaultWorktreeMode", "description": "Default worktree selection for new sessions." }, "EmailNotificationSettings": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether email notifications are enabled", "default": false }, "notification_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notification Email", "description": "Email address to receive notifications" } }, "type": "object", "title": "EmailNotificationSettings", "description": "Settings for email notifications." }, "EnvVar": { "properties": { "key": { "type": "string", "title": "Key", "description": "Environment variable name" }, "value": { "type": "string", "title": "Value", "description": "Environment variable value" } }, "type": "object", "required": [ "key", "value" ], "title": "EnvVar", "description": "A single environment variable key-value pair." }, "GitSettings": { "properties": { "remote": { "type": "string", "title": "Remote", "description": "Git remote to use for push/pull operations (e.g., 'origin')", "default": "origin" }, "base_ref": { "type": "string", "title": "Base Ref", "description": "Base ref/branch for worktrees and checkpoint comparisons (e.g., 'main', 'master')", "default": "main" } }, "type": "object", "title": "GitSettings", "description": "Git-related settings for a workspace." }, "GitUserSettings": { "properties": { "default_worktree_mode": { "$ref": "#/components/schemas/DefaultWorktreeMode", "default": "new_worktree" } }, "additionalProperties": true, "type": "object", "title": "GitUserSettings", "description": "User-level git defaults for new sessions." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HeadRefExistsRequest": { "properties": { "sha": { "type": "string", "title": "Sha" } }, "additionalProperties": false, "type": "object", "required": [ "sha" ], "title": "HeadRefExistsRequest", "description": "Request to check if a head-ref bundle exists." }, "HeadRefExistsResponse": { "properties": { "exists": { "type": "boolean", "title": "Exists" }, "storage_key": { "type": "string", "title": "Storage Key" } }, "additionalProperties": false, "type": "object", "required": [ "exists", "storage_key" ], "title": "HeadRefExistsResponse", "description": "Response indicating if head-ref bundle exists." }, "ImageContent": { "properties": { "type": { "type": "string", "const": "image", "title": "Type", "description": "Content type discriminator", "default": "image" }, "storage_path": { "type": "string", "title": "Storage Path", "description": "Path in Supabase Storage (e.g., 'user_id/abc123.jpg')" }, "media_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/gif", "image/webp" ], "title": "Media Type", "description": "MIME type of the image (e.g., image/png, image/jpeg)" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filename", "description": "Original filename of the uploaded image" }, "size_bytes": { "type": "integer", "title": "Size Bytes", "description": "File size in bytes", "default": 0 } }, "additionalProperties": false, "type": "object", "required": [ "storage_path", "media_type" ], "title": "ImageContent", "description": "Image content - references a file in Supabase Storage." }, "ImportClaudeSessionRequest": { "properties": { "workspace_id": { "type": "string", "title": "Workspace Id", "description": "Workspace ID to import the session into" }, "worktree_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Worktree Name", "description": "Optional worktree name (null for main workspace)" }, "claude_session_id": { "type": "string", "title": "Claude Session Id", "description": "Original Claude CLI session ID (used as SDK resume ID)" }, "messages": { "items": { "$ref": "#/components/schemas/ImportableMessage" }, "type": "array", "title": "Messages", "description": "Messages to import from the Claude CLI session" }, "session_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Name", "description": "Optional name for the imported session" } }, "type": "object", "required": [ "workspace_id", "claude_session_id", "messages" ], "title": "ImportClaudeSessionRequest", "description": "Request to import messages from a Claude CLI session.\n\nThis creates a new user_session and agent_session, then imports all\nthe provided messages into the database. The agent_session_id can then\nbe used as the resume_session_id when starting the SDK." }, "ImportClaudeSessionResponse": { "properties": { "success": { "type": "boolean", "title": "Success", "description": "Whether the import was successful" }, "user_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Session Id", "description": "ID of the created user session" }, "agent_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Session Id", "description": "ID of the created agent session" }, "message_count": { "type": "integer", "title": "Message Count", "description": "Number of messages successfully imported", "default": 0 }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if the import failed" } }, "type": "object", "required": [ "success" ], "title": "ImportClaudeSessionResponse", "description": "Response from importing a Claude CLI session." }, "ImportableMessage": { "properties": { "message_id": { "type": "string", "title": "Message Id", "description": "UUID of the message" }, "role": { "type": "string", "title": "Role", "description": "Role: 'user' or 'assistant'" }, "content": { "$ref": "#/components/schemas/ImportableMessageContent", "description": "Structured content of the message" }, "created_at": { "type": "string", "title": "Created At", "description": "ISO timestamp of when the message was created" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Optional metadata attached to the message" } }, "type": "object", "required": [ "message_id", "role", "content", "created_at" ], "title": "ImportableMessage", "description": "A message to import from Claude CLI session." }, "ImportableMessageContent": { "properties": { "type": { "type": "string", "title": "Type", "description": "Content type: 'text', 'tool_call', 'tool_result', or 'agent_complete'" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "Text content of the message" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Name of the tool being called" }, "tool_use_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool Use Id", "description": "Unique identifier for the tool use" }, "arguments": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Arguments", "description": "Arguments passed to the tool call" }, "output": { "anyOf": [ {}, { "type": "null" } ], "title": "Output", "description": "Output returned from the tool execution" }, "is_error": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Error", "description": "Whether the tool execution resulted in an error" }, "success": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Success", "description": "Whether the agent completed successfully" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Completion message from the agent" } }, "type": "object", "required": [ "type" ], "title": "ImportableMessageContent", "description": "Content for an importable message from Claude CLI." }, "InitWorktreeCheckpointRequest": { "properties": { "worktree_id": { "type": "string", "title": "Worktree Id" }, "base_ref_sha": { "type": "string", "title": "Base Ref Sha" } }, "additionalProperties": false, "type": "object", "required": [ "worktree_id", "base_ref_sha" ], "title": "InitWorktreeCheckpointRequest", "description": "Request to initialize a worktree's checkpoint state to base ref.\n\nCalled when sync is enabled to set the initial checkpoint state,\nindicating the worktree starts from a clean base ref state." }, "InitWorktreeCheckpointResponse": { "properties": { "checkpoint_id": { "type": "string", "title": "Checkpoint Id" }, "synced": { "type": "boolean", "title": "Synced" } }, "additionalProperties": false, "type": "object", "required": [ "checkpoint_id", "synced" ], "title": "InitWorktreeCheckpointResponse", "description": "Response after initializing worktree checkpoint state." }, "MachineDescriptor": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique machine identifier" }, "name": { "type": "string", "title": "Name", "description": "Friendly name unique per user" }, "hostname": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hostname", "description": "OS hostname of the machine" }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Platform", "description": "Operating system platform (e.g. linux, darwin)" }, "architecture": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Architecture", "description": "CPU architecture (e.g. x86_64, arm64)" }, "daemon_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Daemon Version", "description": "Semantic version of the running daemon" }, "status": { "type": "string", "title": "Status", "description": "Current machine status (online, offline, etc.)" }, "last_seen_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Seen At", "description": "Timestamp of the last heartbeat from this machine" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the machine was first registered" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp of the most recent update" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Arbitrary key-value metadata about the machine" } }, "type": "object", "required": [ "id", "name", "status", "created_at", "updated_at" ], "title": "MachineDescriptor", "description": "Serialized machine entity returned to API clients." }, "MachineListResponse": { "properties": { "machines": { "items": { "$ref": "#/components/schemas/MachineDescriptor" }, "type": "array", "title": "Machines", "description": "List of machines ordered by most recently updated" } }, "type": "object", "required": [ "machines" ], "title": "MachineListResponse", "description": "Response containing all machines for the authenticated user." }, "MachineRegisterRequest": { "properties": { "machine_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Machine Id", "description": "Existing machine identifier when re-registering" }, "machine_name": { "type": "string", "title": "Machine Name", "description": "Friendly name unique per user" }, "hostname": { "type": "string", "title": "Hostname", "description": "OS hostname of the machine" }, "platform": { "type": "string", "title": "Platform", "description": "Operating system platform (e.g. linux, darwin)" }, "architecture": { "type": "string", "title": "Architecture", "description": "CPU architecture (e.g. x86_64, arm64)" }, "daemon_version": { "type": "string", "title": "Daemon Version", "description": "Semantic version of the running daemon" }, "directories": { "items": { "type": "string" }, "type": "array", "title": "Directories", "description": "Absolute paths reported by the daemon" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Arbitrary key-value metadata about the machine" } }, "type": "object", "required": [ "machine_name", "hostname", "platform", "architecture", "daemon_version" ], "title": "MachineRegisterRequest", "description": "Request to register or re-register a daemon machine." }, "MachineRegisterResponse": { "properties": { "machine": { "$ref": "#/components/schemas/MachineDescriptor", "description": "Registered machine descriptor" }, "machine_token": { "type": "string", "title": "Machine Token", "description": "Short-lived JWT token for machine WebSocket authentication" }, "machine_token_expires_in": { "type": "integer", "title": "Machine Token Expires In", "description": "Seconds until the machine token expires" }, "machine_ws_path": { "type": "string", "title": "Machine Ws Path", "description": "WebSocket path the daemon should connect to" } }, "type": "object", "required": [ "machine", "machine_token", "machine_token_expires_in", "machine_ws_path" ], "title": "MachineRegisterResponse", "description": "Response after a successful machine registration." }, "MessageEnvelope-Output": { "properties": { "message_id": { "type": "string", "format": "uuid", "title": "Message Id", "description": "Unique message identifier" }, "session_id": { "type": "string", "format": "uuid", "title": "Session Id", "description": "Session this message belongs to" }, "sender": { "$ref": "#/components/schemas/SenderRef", "description": "Reference to the message author" }, "payload": { "$ref": "#/components/schemas/MessagePayload-Output", "description": "The message content and metadata" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Transport-level metadata" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the message was created" }, "delivery_mode": { "anyOf": [ { "type": "string", "enum": [ "queued", "inline" ] }, { "type": "null" } ], "title": "Delivery Mode", "description": "Whether the message was queued or delivered inline" }, "delivered_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Delivered At", "description": "Timestamp when the message was delivered to the AI (null if pending)" }, "canceled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Canceled At", "description": "Timestamp when the message was canceled before delivery" } }, "additionalProperties": false, "type": "object", "required": [ "message_id", "session_id", "sender", "payload", "created_at" ], "title": "MessageEnvelope", "description": "Complete message frame exchanged over transports." }, "MessagePageResponse": { "properties": { "messages": { "items": { "$ref": "#/components/schemas/MessageEnvelope-Output" }, "type": "array", "title": "Messages", "description": "List of message envelopes for this page" }, "has_more": { "type": "boolean", "title": "Has More", "description": "True if more messages exist beyond this page", "default": false }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor (message id) to pass as before_id for the next page" } }, "type": "object", "required": [ "messages" ], "title": "MessagePageResponse", "description": "Paginated response for session messages.\n\nReturns ALL messages for the session regardless of delivery state.\nMessages include delivered_at and canceled_at fields so the frontend\ncan filter/display based on message state:\n- Delivered: delivered_at IS NOT NULL\n- Pending: delivered_at IS NULL AND canceled_at IS NULL\n- Canceled: canceled_at IS NOT NULL AND delivered_at IS NULL" }, "MessagePayload-Output": { "properties": { "version": { "type": "integer", "title": "Version", "description": "Schema version for forward compatibility", "default": 0 }, "content": { "anyOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/ImageContent" }, { "$ref": "#/components/schemas/ToolCallContent" }, { "$ref": "#/components/schemas/ToolResultContent" }, { "$ref": "#/components/schemas/AgentProgressContent" }, { "$ref": "#/components/schemas/AgentCompleteContent" }, { "$ref": "#/components/schemas/SessionStartContent" }, { "$ref": "#/components/schemas/SessionCancelContent" }, { "$ref": "#/components/schemas/CompactionStartedContent" }, { "$ref": "#/components/schemas/CompactionCompletedContent" }, { "$ref": "#/components/schemas/SessionResumedContent" }, { "$ref": "#/components/schemas/ContextUsageContent" } ], "title": "Content", "description": "The typed content body of the message" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Optional metadata associated with the message payload" } }, "additionalProperties": false, "type": "object", "required": [ "content" ], "title": "MessagePayload", "description": "Application-level message data stored in the database and relayed to clients." }, "MobileNotificationMode": { "type": "string", "enum": [ "always", "mobile_only", "never" ], "title": "MobileNotificationMode", "description": "Mobile notification delivery modes." }, "MobileNotificationSettings": { "properties": { "mode": { "$ref": "#/components/schemas/MobileNotificationMode", "description": "When to deliver mobile push notifications", "default": "mobile_only" } }, "type": "object", "title": "MobileNotificationSettings", "description": "Settings for mobile push notifications." }, "NotificationSettings-Input": { "properties": { "mobile": { "$ref": "#/components/schemas/MobileNotificationSettings", "description": "Mobile push notification settings" }, "email": { "$ref": "#/components/schemas/EmailNotificationSettings", "description": "Email notification settings" }, "sms": { "$ref": "#/components/schemas/SmsNotificationSettings", "description": "SMS notification settings" } }, "type": "object", "title": "NotificationSettings", "description": "All notification settings." }, "NotificationSettings-Output": { "properties": { "mobile": { "$ref": "#/components/schemas/MobileNotificationSettings", "description": "Mobile push notification settings" }, "email": { "$ref": "#/components/schemas/EmailNotificationSettings", "description": "Email notification settings" }, "sms": { "$ref": "#/components/schemas/SmsNotificationSettings", "description": "SMS notification settings" } }, "type": "object", "title": "NotificationSettings", "description": "All notification settings." }, "PatSummary": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for the PAT." }, "created_at": { "type": "string", "title": "Created At", "description": "ISO-8601 timestamp when the PAT was created." }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Used At", "description": "ISO-8601 timestamp when the PAT was last used, if ever." } }, "type": "object", "required": [ "id", "created_at" ], "title": "PatSummary", "description": "Summary of a personal access token (PAT) without revealing the token value." }, "RelayClientKind": { "type": "string", "enum": [ "cli", "web", "mobile", "voice" ], "title": "RelayClientKind", "description": "Type of client connecting to the relay." }, "RelayRefreshRequest": { "properties": { "relay_token": { "type": "string", "title": "Relay Token", "description": "Existing relay token to refresh." } }, "type": "object", "required": [ "relay_token" ], "title": "RelayRefreshRequest", "description": "Request to refresh an expiring relay token." }, "RelayRefreshResponse": { "properties": { "relay_token": { "type": "string", "title": "Relay Token", "description": "New relay token for websocket authentication." }, "relay_token_expires_in": { "type": "integer", "title": "Relay Token Expires In", "description": "Seconds until the new relay token expires." } }, "type": "object", "required": [ "relay_token", "relay_token_expires_in" ], "title": "RelayRefreshResponse", "description": "Response containing a new relay token after refresh." }, "RelayRegisterRequest": { "properties": { "user_session_id": { "type": "string", "title": "User Session Id", "description": "Identifier of the user session the relay client will operate within." }, "client_kind": { "anyOf": [ { "$ref": "#/components/schemas/RelayClientKind" }, { "type": "null" } ], "description": "Identifies the caller type (cli, web, mobile, or voice).", "default": "web" } }, "type": "object", "required": [ "user_session_id" ], "title": "RelayRegisterRequest", "description": "Request to register a new relay client for a user session." }, "RelayRegisterResponse": { "properties": { "user_session_id": { "type": "string", "title": "User Session Id", "description": "Identifier of the user session scoped to this relay token." }, "relay_token": { "type": "string", "title": "Relay Token", "description": "Short-lived relay token for websocket authentication." }, "relay_token_expires_in": { "type": "integer", "title": "Relay Token Expires In", "description": "Seconds until the relay token expires." }, "relay_ws_path": { "type": "string", "title": "Relay Ws Path", "description": "WebSocket path for the relay endpoint." }, "relay_heartbeat_interval_sec": { "type": "integer", "title": "Relay Heartbeat Interval Sec", "description": "Heartbeat interval clients should respect." } }, "type": "object", "required": [ "user_session_id", "relay_token", "relay_token_expires_in", "relay_ws_path", "relay_heartbeat_interval_sec" ], "title": "RelayRegisterResponse", "description": "Response containing relay connection credentials after registration." }, "RemoteEnvSettings": { "properties": { "env": { "items": { "$ref": "#/components/schemas/EnvVar" }, "type": "array", "title": "Env", "description": "Environment variables as structured key-value pairs for remote environments" } }, "type": "object", "title": "RemoteEnvSettings", "description": "Remote environment settings for a workspace.\n\nUsed to configure remote environments that can be spun up with specific ENV variables." }, "SenderRef": { "properties": { "kind": { "type": "string", "enum": [ "user", "agent_session", "system" ], "title": "Kind", "description": "Sender type: user, agent_session, or system" }, "id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Id", "description": "Sender identifier (required for user and agent_session, null for system)" } }, "additionalProperties": false, "type": "object", "required": [ "kind" ], "title": "SenderRef", "description": "Reference to the author of a message.\n\nFor user and agent_session senders, id is required.\nFor system senders, id must be None." }, "SessionCancelContent": { "properties": { "type": { "type": "string", "const": "session_cancel", "title": "Type", "description": "Content type discriminator", "default": "session_cancel" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Reason for the cancellation" } }, "additionalProperties": false, "type": "object", "title": "SessionCancelContent", "description": "System message marking a session cancellation.\n\nEmitted when a user cancels an in-progress generation.\nUsed as a marker to invalidate pending messages from before the cancel." }, "SessionResumedContent": { "properties": { "type": { "type": "string", "const": "session_resumed", "title": "Type", "default": "session_resumed" }, "worktree_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Worktree Name" }, "workspace_type": { "type": "string", "enum": [ "LOCAL", "REMOTE" ], "title": "Workspace Type" }, "machine_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Machine Name" } }, "additionalProperties": false, "type": "object", "required": [ "workspace_type" ], "title": "SessionResumedContent", "description": "System message indicating a session was resumed.\n\nEmitted when a session is resumed (e.g., after reconnection or migration).\nUsed to inform the user about the session resumption and current workspace." }, "SessionSettings-Input": { "properties": { "code": { "anyOf": [ { "$ref": "#/components/schemas/CodeAgentSettings-Input" }, { "type": "null" } ] }, "voice": { "anyOf": [ { "$ref": "#/components/schemas/VoiceAgentSettings" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "SessionSettings", "description": "Per-session settings for a user session." }, "SessionSettings-Output": { "properties": { "code": { "anyOf": [ { "$ref": "#/components/schemas/CodeAgentSettings-Output" }, { "type": "null" } ] }, "voice": { "anyOf": [ { "$ref": "#/components/schemas/VoiceAgentSettings" }, { "type": "null" } ] } }, "additionalProperties": true, "type": "object", "title": "SessionSettings", "description": "Per-session settings for a user session." }, "SessionStartContent": { "properties": { "type": { "type": "string", "const": "session_start", "title": "Type", "description": "Content type discriminator", "default": "session_start" } }, "additionalProperties": false, "type": "object", "title": "SessionStartContent", "description": "System message marking the start of a session instance.\n\nUsed as a marker to determine which pending messages are valid\n(only those created after the most recent session_start)." }, "SetupSettings": { "properties": { "script": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Script", "description": "Path to a setup script (relative to workspace root) to run on worktree setup" } }, "type": "object", "title": "SetupSettings", "description": "Setup script settings for a workspace.\n\nConfigures an optional shell script that runs automatically:\n- On worktree creation (local machine)\n- On worktree migration (to/from sandbox)\n- On checkpoint restore\n\nThe script runs with the worktree directory as the working directory." }, "SmsNotificationSettings": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether SMS notifications are enabled", "default": false }, "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number", "description": "Phone number to receive SMS notifications" } }, "type": "object", "title": "SmsNotificationSettings", "description": "Settings for SMS notifications." }, "SyncCheckpointListResponse": { "properties": { "checkpoints": { "items": { "type": "string" }, "type": "array", "title": "Checkpoints" }, "base_ref_bundles": { "items": { "type": "string" }, "type": "array", "title": "Base Ref Bundles" }, "head_ref_bundles": { "items": { "type": "string" }, "type": "array", "title": "Head Ref Bundles" } }, "additionalProperties": false, "type": "object", "required": [ "checkpoints", "base_ref_bundles", "head_ref_bundles" ], "title": "SyncCheckpointListResponse", "description": "Response listing available bundles." }, "SyncDownloadUrlRequest": { "properties": { "bundle_type": { "type": "string", "enum": [ "base_ref", "head_ref", "checkpoint" ], "title": "Bundle Type" }, "sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sha" }, "checkpoint_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checkpoint Id" } }, "additionalProperties": false, "type": "object", "required": [ "bundle_type" ], "title": "SyncDownloadUrlRequest", "description": "Request for a presigned download URL." }, "SyncDownloadUrlResponse": { "properties": { "download_url": { "type": "string", "title": "Download Url" }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At" }, "exists": { "type": "boolean", "title": "Exists" } }, "additionalProperties": false, "type": "object", "required": [ "download_url", "expires_at", "exists" ], "title": "SyncDownloadUrlResponse", "description": "Response containing presigned download URL." }, "SyncSettings": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether remote sync is enabled. When enabled, checkpoints are automatically uploaded after each agent turn.", "default": false } }, "type": "object", "title": "SyncSettings", "description": "Remote sync settings for a workspace.\n\nWhen enabled, checkpoints are automatically uploaded after each agent turn." }, "SyncStateResponse": { "properties": { "last_base_ref_sync_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Base Ref Sync At" }, "last_base_ref_sync_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Base Ref Sync Ref" }, "last_base_ref_sync_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Base Ref Sync Sha" }, "synced_head_refs": { "items": { "type": "string" }, "type": "array", "title": "Synced Head Refs" }, "synced_checkpoints": { "items": { "type": "string" }, "type": "array", "title": "Synced Checkpoints" } }, "additionalProperties": false, "type": "object", "required": [ "synced_head_refs", "synced_checkpoints" ], "title": "SyncStateResponse", "description": "Current sync state for a workspace." }, "SyncStateUpdateRequest": { "properties": { "last_base_ref_sync_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Base Ref Sync Ref" }, "last_base_ref_sync_sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Base Ref Sync Sha" }, "add_synced_head_refs": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Add Synced Head Refs" }, "add_synced_checkpoints": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Add Synced Checkpoints" } }, "additionalProperties": false, "type": "object", "title": "SyncStateUpdateRequest", "description": "Request to update sync state after successful upload." }, "SyncUploadUrlRequest": { "properties": { "bundle_type": { "type": "string", "enum": [ "base_ref", "head_ref", "checkpoint" ], "title": "Bundle Type" }, "sha": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sha" }, "checkpoint_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checkpoint Id" } }, "additionalProperties": false, "type": "object", "required": [ "bundle_type" ], "title": "SyncUploadUrlRequest", "description": "Request for a presigned upload URL (legacy)." }, "SyncUploadUrlResponse": { "properties": { "upload_url": { "type": "string", "title": "Upload Url" }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At" }, "storage_key": { "type": "string", "title": "Storage Key" } }, "additionalProperties": false, "type": "object", "required": [ "upload_url", "expires_at", "storage_key" ], "title": "SyncUploadUrlResponse", "description": "Response containing presigned upload URL (legacy)." }, "SyncUserRequest": { "properties": { "id": { "type": "string", "title": "Id", "description": "Supabase user identifier to sync." }, "email": { "type": "string", "title": "Email", "description": "Email address from Supabase." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "Display name from Supabase profile." } }, "type": "object", "required": [ "id", "email" ], "title": "SyncUserRequest", "description": "Request body for syncing a Supabase user to the local database." }, "TextContent": { "properties": { "type": { "type": "string", "const": "text", "title": "Type", "description": "Content type discriminator", "default": "text" }, "text": { "type": "string", "title": "Text", "description": "The text content of the message" }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Channel", "description": "Optional channel for text variants (e.g., 'reasoning')" }, "annotations": { "items": { "type": "string" }, "type": "array", "title": "Annotations", "description": "Text annotations or markers" }, "attachments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ImageContent" }, "type": "array" }, { "type": "null" } ], "title": "Attachments", "description": "Optional inline image attachments delivered with the text message" } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "TextContent", "description": "Plain text content shared with the agent." }, "ToolCallContent": { "properties": { "type": { "type": "string", "const": "tool_call", "title": "Type", "description": "Content type discriminator", "default": "tool_call" }, "name": { "type": "string", "title": "Name", "description": "Name of the tool being invoked" }, "tool_use_id": { "type": "string", "title": "Tool Use Id", "description": "Unique identifier for this tool invocation" }, "arguments": { "additionalProperties": true, "type": "object", "title": "Arguments", "description": "Arguments passed to the tool" } }, "additionalProperties": false, "type": "object", "required": [ "name", "tool_use_id", "arguments" ], "title": "ToolCallContent", "description": "Tool invocation authored by the assistant." }, "ToolResultContent": { "properties": { "type": { "type": "string", "const": "tool_result", "title": "Type", "description": "Content type discriminator", "default": "tool_result" }, "tool_use_id": { "type": "string", "title": "Tool Use Id", "description": "Identifier of the tool invocation this result corresponds to" }, "output": { "title": "Output", "description": "Output value produced by the tool" }, "is_error": { "type": "boolean", "title": "Is Error", "description": "Whether the tool execution resulted in an error", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "tool_use_id", "output" ], "title": "ToolResultContent", "description": "Result produced by a previously invoked tool." }, "UpdateProfileRequest": { "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "New display name (null to clear)." } }, "type": "object", "title": "UpdateProfileRequest", "description": "Request body for updating the current user's profile." }, "UpdateUserSessionRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "New name for the session" }, "session_settings": { "anyOf": [ { "$ref": "#/components/schemas/SessionSettings-Input" }, { "type": "null" } ], "description": "User session settings for code/voice agents" } }, "type": "object", "title": "UpdateUserSessionRequest", "description": "Payload for updating a user session." }, "UserProfile": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique user identifier." }, "email": { "type": "string", "title": "Email", "description": "User email address." }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name", "description": "User-chosen display name." }, "created_at": { "type": "string", "title": "Created At", "description": "ISO-8601 timestamp of account creation." } }, "type": "object", "required": [ "id", "email", "created_at" ], "title": "UserProfile", "description": "Public profile of the authenticated user." }, "UserSessionDescriptor": { "properties": { "kind": { "type": "string", "const": "user_session", "title": "Kind", "description": "Descriptor type discriminator", "default": "user_session" }, "session_id": { "type": "string", "format": "uuid", "title": "Session Id", "description": "Unique session identifier" }, "user_id": { "type": "string", "format": "uuid", "title": "User Id", "description": "Owner user identifier" }, "status": { "$ref": "#/components/schemas/UserSessionStatus", "description": "Current session status" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the session was created" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Optional user-defined session name" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Arbitrary session metadata" }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/SessionSettings-Output" }, { "type": "null" } ], "description": "Session settings for code and voice agents" }, "worktree_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Worktree Id", "description": "Associated worktree identifier" }, "worktree_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Worktree Name", "description": "Name of the associated worktree" }, "worktree_type": { "anyOf": [ { "$ref": "#/components/schemas/WorktreeType" }, { "type": "null" } ], "description": "Type of the associated worktree (LOCAL or REMOTE)" } }, "additionalProperties": false, "type": "object", "required": [ "session_id", "user_id", "status", "created_at" ], "title": "UserSessionDescriptor", "description": "Representation of a user-owned conversation container." }, "UserSessionStatus": { "type": "string", "enum": [ "ACTIVE", "COMPLETED", "DELETED" ], "title": "UserSessionStatus" }, "UserSessionSummary": { "properties": { "session": { "$ref": "#/components/schemas/UserSessionDescriptor", "description": "Core user session descriptor" }, "agent_sessions": { "items": { "$ref": "#/components/schemas/AgentSessionDescriptor-Output" }, "type": "array", "title": "Agent Sessions", "description": "Agent sessions associated with this user session" }, "workspace": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceDescriptor" }, { "type": "null" } ], "description": "Workspace linked to this session, if any" }, "worktree": { "anyOf": [ { "$ref": "#/components/schemas/WorktreeDescriptor" }, { "type": "null" } ], "description": "Worktree linked to this session, if any" } }, "type": "object", "required": [ "session" ], "title": "UserSessionSummary", "description": "Aggregated user session data returned to clients." }, "UserSettings": { "properties": { "notifications": { "$ref": "#/components/schemas/NotificationSettings-Output", "description": "Notification preferences for the user" }, "git": { "$ref": "#/components/schemas/GitUserSettings", "description": "User-level git defaults for new sessions" }, "code": { "$ref": "#/components/schemas/CodeAgentSettings-Output", "description": "Code agent settings across providers" }, "voice": { "$ref": "#/components/schemas/VoiceAgentSettings", "description": "Voice agent settings" } }, "additionalProperties": true, "type": "object", "title": "UserSettings", "description": "Complete user settings stored as JSONB." }, "UserSettingsUpdateRequest": { "properties": { "notifications": { "anyOf": [ { "$ref": "#/components/schemas/NotificationSettings-Input" }, { "type": "null" } ], "description": "Notification preferences for the user" }, "git": { "anyOf": [ { "$ref": "#/components/schemas/GitUserSettings" }, { "type": "null" } ], "description": "User-level git defaults for new sessions" }, "code": { "anyOf": [ { "$ref": "#/components/schemas/CodeAgentSettings-Input" }, { "type": "null" } ], "description": "Code agent settings across providers" }, "voice": { "anyOf": [ { "$ref": "#/components/schemas/VoiceAgentSettings" }, { "type": "null" } ], "description": "Voice agent settings" } }, "additionalProperties": true, "type": "object", "title": "UserSettingsUpdateRequest", "description": "Patch request for updating user settings." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VoiceAgentSettings": { "properties": { "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language" } }, "additionalProperties": true, "type": "object", "title": "VoiceAgentSettings", "description": "Settings for the voice agent." }, "WorkspaceConfig-Output": { "properties": { "git": { "$ref": "#/components/schemas/GitSettings", "description": "Git settings (remote and base ref) for the workspace" }, "sync": { "$ref": "#/components/schemas/SyncSettings", "description": "Remote sync settings for automatic checkpoint uploads" }, "remote_env": { "$ref": "#/components/schemas/RemoteEnvSettings", "description": "Remote environment settings including environment variables" }, "setup": { "$ref": "#/components/schemas/SetupSettings", "description": "Setup script settings for automatic worktree initialization" } }, "type": "object", "title": "WorkspaceConfig", "description": "Workspace-level configuration persisted alongside metadata." }, "WorkspaceConfigUpdateRequest": { "properties": { "git": { "anyOf": [ { "$ref": "#/components/schemas/GitSettings" }, { "type": "null" } ], "description": "Git settings (remote and base_ref) for the workspace" }, "sync": { "anyOf": [ { "$ref": "#/components/schemas/SyncSettings" }, { "type": "null" } ], "description": "Sync settings for automatic checkpoint uploads" }, "remote_env": { "anyOf": [ { "$ref": "#/components/schemas/RemoteEnvSettings" }, { "type": "null" } ], "description": "Remote environment settings for spinning up remote environments" }, "setup": { "anyOf": [ { "$ref": "#/components/schemas/SetupSettings" }, { "type": "null" } ], "description": "Setup script settings for automatic worktree initialization" } }, "type": "object", "title": "WorkspaceConfigUpdateRequest", "description": "Request body for updating workspace configuration." }, "WorkspaceDescriptor": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique workspace identifier" }, "user_id": { "type": "string", "title": "User Id", "description": "Owner user identifier" }, "git_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Git Host", "description": "Canonical git host (e.g., github.com)" }, "git_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Git Path", "description": "Canonical git repository path (e.g., org/repo)" }, "workspace_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Workspace Metadata", "description": "Arbitrary workspace metadata (labels, annotations)" }, "workspace_config": { "$ref": "#/components/schemas/WorkspaceConfig-Output", "description": "Workspace configuration including git, sync, and remote environment settings" }, "user_machine_paths": { "items": { "$ref": "#/components/schemas/shared__schemas__api_workspaces__UserMachinePathDescriptor" }, "type": "array", "title": "User Machine Paths", "description": "Machines linked to this workspace with their local paths" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the workspace was created" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the workspace was last updated" } }, "type": "object", "required": [ "id", "user_id", "created_at", "updated_at" ], "title": "WorkspaceDescriptor", "description": "Serialized workspace row returned to API clients." }, "WorkspaceEnsureRequest": { "properties": { "machine_id": { "type": "string", "title": "Machine Id", "description": "Identifier of the daemon machine" }, "local_path": { "type": "string", "title": "Local Path", "description": "Absolute path reported by the daemon" }, "git_host": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Git Host", "description": "Canonical git host if detected (e.g., github.com)" }, "git_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Git Path", "description": "Canonical git path if detected (e.g., org/repo)" }, "workspace_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Workspace Metadata", "description": "Optional workspace metadata (labels, annotations, etc.)" }, "git_settings": { "anyOf": [ { "$ref": "#/components/schemas/GitSettings" }, { "type": "null" } ], "description": "Detected git settings (remote, base_ref) for the workspace" } }, "type": "object", "required": [ "machine_id", "local_path" ], "title": "WorkspaceEnsureRequest", "description": "Payload for creating or updating a workspace from the daemon." }, "WorkspaceSessionLaunchRequest": { "properties": { "machine_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Machine Id", "description": "Machine ID to launch the session on. If not provided, uses the workspace's default machine." }, "user_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Session Id", "description": "Existing user session to reuse" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Arbitrary metadata describing the launch" }, "initial_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Initial Prompt", "description": "Prompt delivered to the coding agent at startup" }, "worktree_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Worktree Name", "description": "Name for the git worktree/branch to use for this session" }, "session_settings": { "anyOf": [ { "$ref": "#/components/schemas/SessionSettings-Input" }, { "type": "null" } ], "description": "Optional session settings overrides for this launch" }, "resume_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resume Session Id", "description": "SDK session ID to resume from (e.g., from Claude CLI import)" }, "agent_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Session Id", "description": "Existing agent session ID to connect to (e.g., from import)" } }, "type": "object", "title": "WorkspaceSessionLaunchRequest", "description": "Request body used to start a session for a workspace." }, "WorkspaceSessionLaunchResponse": { "properties": { "status": { "type": "string", "title": "Status", "description": "Launch status (e.g., 'ok', 'error')" }, "payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Payload", "description": "Optional response payload with additional details" } }, "type": "object", "required": [ "status" ], "title": "WorkspaceSessionLaunchResponse", "description": "Daemon acknowledgement returned after a launch request." }, "WorktreeDescriptor": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique worktree identifier" }, "workspace_id": { "type": "string", "title": "Workspace Id", "description": "Parent workspace identifier" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Worktree name (null for the main worktree)" }, "is_main": { "type": "boolean", "title": "Is Main", "description": "Whether this is the main/default worktree for the workspace" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Path", "description": "Filesystem path for the worktree on the machine" }, "worktree_type": { "anyOf": [ { "type": "string", "enum": [ "LOCAL", "REMOTE" ] }, { "type": "null" } ], "title": "Worktree Type", "description": "Type of worktree: LOCAL (user machine) or REMOTE (sandbox)" }, "user_machine_path": { "anyOf": [ { "$ref": "#/components/schemas/shared__schemas__worktree__UserMachinePathDescriptor" }, { "type": "null" } ], "description": "Machine+path link when worktree_type is LOCAL" }, "managed_machine_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Managed Machine Id", "description": "Managed machine ID if worktree_type is REMOTE" }, "last_heartbeat_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Heartbeat At", "description": "Most recent liveness heartbeat received from the sandbox container (REMOTE only)." }, "last_synced_checkpoint_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Synced Checkpoint Id", "description": "ID of the last checkpoint that was successfully synced to cloud storage. This may differ from current_checkpoint_id if a recent checkpoint failed to sync." }, "checkpoint_restore_pending": { "type": "boolean", "title": "Checkpoint Restore Pending", "description": "Whether a checkpoint needs to be restored on next local session start", "default": false }, "current_checkpoint_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Checkpoint Id", "description": "Identifier of the current checkpoint for this worktree" }, "checkpoint_metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Checkpoint Metadata", "description": "Metadata associated with the current checkpoint (e.g., commit info)" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp when the worktree was created" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Timestamp when the worktree was last updated" } }, "additionalProperties": false, "type": "object", "required": [ "id", "workspace_id", "is_main", "created_at", "updated_at" ], "title": "WorktreeDescriptor", "description": "Serialized worktree entity returned to API clients." }, "WorktreeEnsureRequest": { "properties": { "workspace_id": { "type": "string", "title": "Workspace Id", "description": "Workspace ID to create worktree in" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Worktree name (null for main worktree)" }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Path", "description": "Filesystem path for the worktree (null for main worktree)" } }, "additionalProperties": false, "type": "object", "required": [ "workspace_id" ], "title": "WorktreeEnsureRequest", "description": "Request to ensure a worktree exists, creating if needed." }, "WorktreeMigrateRequest": { "properties": { "target_type": { "type": "string", "enum": [ "LOCAL", "REMOTE" ], "title": "Target Type", "description": "Target type: LOCAL (user machine) or REMOTE (sandbox)" }, "target_machine_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Machine Id", "description": "Target user machine ID (required for LOCAL, ignored for REMOTE)" }, "source": { "type": "string", "enum": [ "checkpoint", "base_ref" ], "title": "Source", "description": "Source for REMOTE migration: 'checkpoint' uses current checkpoint, 'base_ref' starts fresh from workspace base ref (requires sync enabled)", "default": "checkpoint" }, "worktree_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Worktree Name", "description": "Name for new worktree when using source='base_ref'. If provided, creates a new worktree with this name instead of migrating existing one." } }, "additionalProperties": false, "type": "object", "required": [ "target_type" ], "title": "WorktreeMigrateRequest", "description": "Request to migrate a worktree to a different machine type." }, "WorktreeMigrateResponse": { "properties": { "worktree": { "$ref": "#/components/schemas/WorktreeDescriptor", "description": "Updated worktree descriptor" }, "status": { "type": "string", "const": "migrated", "title": "Status", "description": "Status of the migration: 'migrated' on success" } }, "additionalProperties": false, "type": "object", "required": [ "worktree", "status" ], "title": "WorktreeMigrateResponse", "description": "Response after migrating a worktree." }, "WorktreeSetRequest": { "properties": { "worktree_id": { "type": "string", "title": "Worktree Id", "description": "Worktree ID to associate with session" } }, "additionalProperties": false, "type": "object", "required": [ "worktree_id" ], "title": "WorktreeSetRequest", "description": "Request to set a user session's worktree." }, "WorktreeType": { "type": "string", "enum": [ "LOCAL", "REMOTE" ], "title": "WorktreeType", "description": "Whether a worktree runs on a user's local machine or a managed remote machine." }, "shared__schemas__api_workspaces__UserMachinePathDescriptor": { "properties": { "user_machine_id": { "type": "string", "title": "User Machine Id", "description": "Identifier of the linked user machine" }, "local_path": { "type": "string", "title": "Local Path", "description": "Absolute filesystem path to the workspace on the machine" } }, "type": "object", "required": [ "user_machine_id", "local_path" ], "title": "UserMachinePathDescriptor", "description": "A user machine path linked to a workspace." }, "shared__schemas__worktree__UserMachinePathDescriptor": { "properties": { "id": { "type": "string", "title": "Id" }, "machine_id": { "type": "string", "title": "Machine Id" }, "local_path": { "type": "string", "title": "Local Path" } }, "type": "object", "required": [ "id", "machine_id", "local_path" ], "title": "UserMachinePathDescriptor", "description": "Machine path information associated with a LOCAL worktree." } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "x-stability": "unstable" }