---
title: "Update User Session"
method: PATCH
path: "/api/v1/user-sessions/{user_session_id}"
tags: ["user_sessions"]
---

# Update User Session

`PATCH /api/v1/user-sessions/{user_session_id}`

Update a user session (e.g., rename).

Returns 404 if the session is not found or has been deleted.

## Path parameters

- `user_session_id` string, required

## Request body

- UpdateUserSessionRequest — Payload for updating a user session.
  - `name` string, nullable — New name for the session
  - `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

## Response `200`

Successful Response

- UserSessionDescriptor — 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.

## 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)