---
title: "Create User Session Endpoint"
method: POST
path: "/api/v1/user-sessions"
tags: ["user_sessions"]
---

# Create User Session Endpoint

`POST /api/v1/user-sessions`

Create a new user session container for the authenticated user.

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

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

## Request body

- CreateUserSessionRequest — Payload for creating or reusing a user session container.
  - `worktree_id` string, nullable — Worktree identifier linked to this session (preferred)
  - `workspace_id` string, nullable — Deprecated: Use worktree_id instead. If worktree_id is not provided, the main worktree for this workspace will be used.
  - `user_session_id` string, nullable — Optional explicit user session id to reuse or create
  - `name` string, nullable — Optional human-readable session name
  - `metadata` object, nullable — Arbitrary key-value metadata for the session
  - `start_sandbox` boolean — If True and worktree is REMOTE, start the sandbox session immediately
  - `session_settings` SessionSettingsInput — Per-session settings for a user session.
    - `code` CodeAgentSettingsInput — Settings for the code agent across providers.
      - `mode` 'agent' | 'orchestrator', nullable
      - `default_provider` string, nullable
      - `providers` CodeAgentProviders — Provider-specific code agent settings keyed by provider name.
        - `claude_code` ClaudeCodeSettings — Claude-specific settings for the code agent.
          - `model` 'haiku' | 'sonnet' | 'opus' | 'opus[1m]', nullable
        - `codex` CodexSettings — Codex-specific settings for the code agent.
          - `model` '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', nullable
          - `thinking` 'low' | 'medium' | 'high' | 'xhigh', nullable
    - `voice` VoiceAgentSettings — Settings for the voice agent.
      - `language` string, nullable
  - `initial_message` string, nullable — Initial message to queue for the agent. This message will be delivered as soon as the agent connects, eliminating the frontend waterfall delay.

## Response `201`

Successful Response

- UserSessionSummary — Aggregated user session data returned to clients.
  - `session` UserSessionDescriptor, required — Representation of a user-owned conversation container.
    - `kind` 'user_session' — Descriptor type discriminator
    - `session_id` string, uuid, required — Unique session identifier
    - `user_id` string, uuid, required — Owner user identifier
    - `status` 'ACTIVE' | 'COMPLETED' | 'DELETED', required
    - `created_at` string, date-time, required — Timestamp when the session was created
    - `name` string, nullable — Optional user-defined session name
    - `metadata` object, nullable — Arbitrary session metadata
    - `settings` SessionSettingsOutput — Per-session settings for a user session.
      - `code` CodeAgentSettingsOutput — Settings for the code agent across providers.
        - `mode` 'agent' | 'orchestrator', nullable
        - `default_provider` string, nullable
        - `providers` CodeAgentProviders — Provider-specific code agent settings keyed by provider name.
          - `claude_code` ClaudeCodeSettings — Claude-specific settings for the code agent.
            - `model` 'haiku' | 'sonnet' | 'opus' | 'opus[1m]', nullable
          - `codex` CodexSettings — Codex-specific settings for the code agent.
            - `model` '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', nullable
            - `thinking` 'low' | 'medium' | 'high' | 'xhigh', nullable
      - `voice` VoiceAgentSettings — Settings for the voice agent.
        - `language` string, nullable
    - `worktree_id` string, uuid, nullable — Associated worktree identifier
    - `worktree_name` string, nullable — Name of the associated worktree
    - `worktree_type` 'LOCAL' | 'REMOTE' — Whether a worktree runs on a user's local machine or a managed remote machine.
  - `agent_sessions` AgentSessionDescriptorOutput[] — Agent sessions associated with this user session
    - `kind` 'agent_session' — Descriptor type discriminator
    - `session_id` string, uuid, required — Unique agent session identifier
    - `user_session_id` string, uuid, nullable — Parent user session identifier
    - `parent_session_id` string, uuid, nullable — Parent agent session identifier (for sub-agents)
    - `session_type` 'CODE' | 'VOICE', required
    - `connection_status` 'CONNECTED' | 'DISCONNECTED', required
    - `work_status` 'IDLE' | 'WORKING' | 'COMPLETED', required
    - `daemon_version` string, nullable — Version of the daemon running this session
    - `metadata` object, nullable — Arbitrary agent session metadata
    - `settings` SessionSettingsOutput — Per-session settings for a user session.
      - `code` CodeAgentSettingsOutput — Settings for the code agent across providers.
        - `mode` 'agent' | 'orchestrator', nullable
        - `default_provider` string, nullable
        - `providers` CodeAgentProviders — Provider-specific code agent settings keyed by provider name.
          - `claude_code` ClaudeCodeSettings — Claude-specific settings for the code agent.
            - `model` 'haiku' | 'sonnet' | 'opus' | 'opus[1m]', nullable
          - `codex` CodexSettings — Codex-specific settings for the code agent.
            - `model` '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', nullable
            - `thinking` 'low' | 'medium' | 'high' | 'xhigh', nullable
      - `voice` VoiceAgentSettings — Settings for the voice agent.
        - `language` string, nullable
  - `workspace` WorkspaceDescriptor — Serialized workspace row returned to API clients.
    - `id` string, required — Unique workspace identifier
    - `user_id` string, required — Owner user identifier
    - `git_host` string, nullable — Canonical git host (e.g., github.com)
    - `git_path` string, nullable — Canonical git repository path (e.g., org/repo)
    - `workspace_metadata` object, nullable — Arbitrary workspace metadata (labels, annotations)
    - `workspace_config` WorkspaceConfigOutput — Workspace-level configuration persisted alongside metadata.
      - `git` GitSettings — Git-related settings for a workspace.
        - `remote` string — Git remote to use for push/pull operations (e.g., 'origin')
        - `base_ref` string — Base ref/branch for worktrees and checkpoint comparisons (e.g., 'main', 'master')
      - `sync` SyncSettings — Remote sync settings for a workspace. When enabled, checkpoints are automatically uploaded after each agent turn.
        - `enabled` boolean — Whether remote sync is enabled. When enabled, checkpoints are automatically uploaded after each agent turn.
      - `remote_env` RemoteEnvSettings — Remote environment settings for a workspace. Used to configure remote environments that can be spun up with specific ENV variables.
        - `env` EnvVar[] — Environment variables as structured key-value pairs for remote environments
          - `key` string, required — Environment variable name
          - `value` string, required — Environment variable value
      - `setup` SetupSettings — Setup script settings for a workspace. Configures an optional shell script that runs automatically: - On worktree creation (local machine) - On worktree migration (to/from sandbox) - On checkpoint restore The script runs with the worktree directory as the working directory.
        - `script` string, nullable — Path to a setup script (relative to workspace root) to run on worktree setup
    - `user_machine_paths` SharedSchemasApiWorkspacesUserMachinePathDescriptor[] — Machines linked to this workspace with their local paths
      - `user_machine_id` string, required — Identifier of the linked user machine
      - `local_path` string, required — Absolute filesystem path to the workspace on the machine
    - `created_at` string, date-time, required — Timestamp when the workspace was created
    - `updated_at` string, date-time, required — Timestamp when the workspace was last updated
  - `worktree` WorktreeDescriptor — Serialized worktree entity returned to API clients.
    - `id` string, required — Unique worktree identifier
    - `workspace_id` string, required — Parent workspace identifier
    - `name` string, nullable — Worktree name (null for the main worktree)
    - `is_main` boolean, required — Whether this is the main/default worktree for the workspace
    - `path` string, nullable — Filesystem path for the worktree on the machine
    - `worktree_type` 'LOCAL' | 'REMOTE', nullable — Type of worktree: LOCAL (user machine) or REMOTE (sandbox)
    - `user_machine_path` SharedSchemasWorktreeUserMachinePathDescriptor — Machine path information associated with a LOCAL worktree.
      - `id` string, required
      - `machine_id` string, required
      - `local_path` string, required
    - `managed_machine_id` string, nullable — Managed machine ID if worktree_type is REMOTE
    - `last_heartbeat_at` string, date-time, nullable — Most recent liveness heartbeat received from the sandbox container (REMOTE only).
    - `last_synced_checkpoint_id` string, nullable — 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` boolean — Whether a checkpoint needs to be restored on next local session start
    - `current_checkpoint_id` string, nullable — Identifier of the current checkpoint for this worktree
    - `checkpoint_metadata` object, nullable — Metadata associated with the current checkpoint (e.g., commit info)
    - `created_at` string, date-time, required — Timestamp when the worktree was created
    - `updated_at` string, date-time, required — Timestamp when the worktree was last updated

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/omnara/apis/omnara-api.md) · [All operations](https://skmtc.dev/omnara/apis/omnara-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omnara/omnara-api/revisions/624048e40cad/schema)