---
title: "Update User Settings"
method: PATCH
path: "/api/v1/user/settings"
tags: ["user-settings"]
---

# Update User Settings

`PATCH /api/v1/user/settings`

Partially update the current user's settings.

Accepts optional fields to modify across all user settings, including
notification preferences such as mobile notification mode, email and SMS
toggles, phone number, and notification email. Validates phone numbers
against E.164 format and ensures a phone number is present when SMS
notifications are enabled.

## Request body

- UserSettingsUpdateRequest — Patch request for updating user settings.
  - `notifications` NotificationSettingsInput — All notification settings.
    - `mobile` MobileNotificationSettings — Settings for mobile push notifications.
      - `mode` 'always' | 'mobile_only' | 'never' — Mobile notification delivery modes.
    - `email` EmailNotificationSettings — Settings for email notifications.
      - `enabled` boolean — Whether email notifications are enabled
      - `notification_email` string, nullable — Email address to receive notifications
    - `sms` SmsNotificationSettings — Settings for SMS notifications.
      - `enabled` boolean — Whether SMS notifications are enabled
      - `phone_number` string, nullable — Phone number to receive SMS notifications
  - `git` GitUserSettings — User-level git defaults for new sessions.
    - `default_worktree_mode` 'new_worktree' | 'repo_root' — Default worktree selection for new sessions.
  - `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

- UserSettings — Complete user settings stored as JSONB.
  - `notifications` NotificationSettingsOutput — All notification settings.
    - `mobile` MobileNotificationSettings — Settings for mobile push notifications.
      - `mode` 'always' | 'mobile_only' | 'never' — Mobile notification delivery modes.
    - `email` EmailNotificationSettings — Settings for email notifications.
      - `enabled` boolean — Whether email notifications are enabled
      - `notification_email` string, nullable — Email address to receive notifications
    - `sms` SmsNotificationSettings — Settings for SMS notifications.
      - `enabled` boolean — Whether SMS notifications are enabled
      - `phone_number` string, nullable — Phone number to receive SMS notifications
  - `git` GitUserSettings — User-level git defaults for new sessions.
    - `default_worktree_mode` 'new_worktree' | 'repo_root' — Default worktree selection for new sessions.
  - `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

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