---
title: "PUT /settings"
method: PUT
path: "/settings"
tags: ["settings"]
---

# PUT /settings

`PUT /settings`

Updates application settings. Accepts a partial settings object and merges it
with the existing settings.

NOTE: Unlike the Tauri command, this handler does NOT apply OS-level side
effects (no autostart registration, no keyboard shortcut updates). It only
persists the settings domain model.

## Request body

- SettingsPatchDto
  - `fileSync` FileSyncSettingsPatchDto
    - `autoSaveDir` string, nullable — Absent = leave unchanged; `""` = clear (managed storage); a path = save inbound files there.
    - `fileAutoCleanup` boolean, nullable
    - `fileCacheQuotaPerDevice` integer, nullable
    - `fileRetentionHours` integer, nullable
    - `fileSyncEnabled` boolean, nullable
    - `maxFileSize` integer, nullable
    - `smallFileThreshold` integer, nullable
  - `general` GeneralSettingsPatchDto — All fields are optional — only provided fields are updated.
    - `autoCheckUpdate` boolean, nullable
    - `autoDownloadUpdate` boolean, nullable
    - `autoStart` boolean, nullable
    - `debugMode` boolean, nullable
    - `deviceName` string, nullable
    - `language` string, nullable
    - `restoreLastEntryOnStartup` boolean, nullable
    - `startupMode` 'normal' | 'silent' | 'lightweight'
    - `telemetryEnabled` boolean, nullable
    - `theme` 'light' | 'dark' | 'system'
    - `themeColor` string, nullable — 旧版"统一主题预设"patch 字段。`Some(None)` = 显式清空,`None` = 不修改。
    - `themeColorDark` string, nullable — Dark 模式预设 patch。`Some(None)` = 显式清空（回退到 `theme_color` 或引擎默认）。
    - `themeColorLight` string, nullable — Light 模式预设 patch。`Some(None)` = 显式清空（回退到 `theme_color` 或引擎默认）。
    - `themeOverridesDark` object, nullable — Dark 模式 overrides patch（语义同 light）。
    - `themeOverridesLight` object, nullable — Light 模式 overrides patch。`Some(map)` 整体替换；`None` 表示不修改。
    - `updateChannel` 'stable' | 'alpha' | 'beta' | 'rc'
    - `usageAnalyticsEnabled` boolean, nullable
  - `keyboardShortcuts` KeyboardShortcutsPatchDto
    - `shortcuts` object, required
  - `network` NetworkSettingsPatchDto — LAN-only Mode 字段 patch DTO 镜像 — `null` = 不修改。
    - `allowOverlayNetworkAddrs` boolean, nullable
    - `allowRelayFallback` boolean, nullable
    - `congestionController` 'cubic' | 'bbr3' — Algorithm for network flow control. Wire form: `"cubic"` | `"bbr3"`.
    - `customRelayUrls` string[], nullable
  - `pairing` PairingSettingsPatchDto
    - `maxRetries` integer, nullable
    - `sessionTimeout` integer, nullable
    - `stepTimeout` integer, nullable
    - `userVerificationTimeout` integer, nullable
  - `quickPanel` QuickPanelSettingsPatchDto — 快捷面板字段 patch DTO 镜像 — `null` = 不修改。
    - `doubleTapModifier` 'disabled' | 'alt' | 'control' | 'meta'
    - `enabled` boolean, nullable
    - `position` 'center' | 'follow_cursor' — 快捷面板出现位置 DTO。wire form: `center` | `follow_cursor`。
  - `retentionPolicy` RetentionPolicyPatchDto
    - `enabled` boolean, nullable
    - `evaluation` 'anyMatch' | 'allMatch'
    - `rules` RetentionRuleDto[], nullable
      - union
        - object
          - `byAge` object, required — 按时间清理
            - `max_age` integer, required
        - object
          - `byCount` object, required — 按总数量上限
            - `max_items` integer, required
        - object
          - `byContentType` object, required — 按内容类型的最大存活时间
            - `content_type` ContentTypesDto, required
              - …
            - `max_age` integer, required
        - object
          - `byTotalSize` object, required — 按磁盘占用大小
            - `max_bytes` integer, required
        - object
          - `sensitive` object, required — 敏感内容快速过期
            - `max_age` integer, required
    - `skipPinned` boolean, nullable
  - `security` SecuritySettingsPatchDto
    - `autoUnlockEnabled` boolean, nullable — 写入时设置是否启用启动时自动解锁
    - `encryptionEnabled` boolean, nullable — 写入时设置是否启用本地数据加密（需要 passphrase）
    - `passphrase` string, nullable — 写入时设置 passphrase（由前端/daemon 内部触发解锁流程）
  - `sync` SyncSettingsPatchDto
    - `autoSync` boolean, nullable
    - `contentTypes` ContentTypesPatchDto
      - `codeSnippet` boolean, nullable
      - `file` boolean, nullable
      - `image` boolean, nullable
      - `link` boolean, nullable
      - `richText` boolean, nullable
      - `text` boolean, nullable
    - `syncFrequency` 'realtime' | 'interval'
    - `syncOnRestore` boolean, nullable

## Response `200`

Settings persisted; carries success + restart-required signal

- SettingsUpdateResultEnvelope — Canonical success envelope: `{ "data": T, "ts": <unix millis i64> }`. `ts` is `chrono::Utc::now().timestamp_millis()`, set in the webserver handler via [`ApiEnvelope::now`] (the contract carries only the type + the clock helper, not a hard dependency on when the handler reads the clock). `rename_all = "camelCase"` is a no-op for the single-word fields here but is declared for forward-compat. IMPORTANT (utoipa v4): every concrete `ApiEnvelope<X>` that needs a named OpenAPI component is declared in the `#[aliases(...)]` block below. Add a new alias line whenever a new payload type needs enveloping. NEVER register the bare `ApiEnvelope` in `components(schemas(...))` — utoipa errors on a bare generic, and an un-aliased generic inlines an anonymous schema.
  - `data` SettingsUpdateResultDto, required — Folded payload for `PUT /settings` (ADR-008 §0.1). The current handler returns `success` and `restartRequired` as top-level siblings of the `{data,ts}` envelope. This DTO folds those siblings INTO the payload so the endpoint can return `ApiEnvelope<SettingsUpdateResultDto>` with no bespoke wrapper. P1 only defines the type; the handler is rewired in P2.
    - `restartRequired` boolean, required — Whether the patch touched fields requiring a daemon restart (currently only `network.*`).
    - `success` boolean, required
  - `ts` integer, required — Server time when the response was built (unix epoch milliseconds).

## Other responses

- `400` — Invalid request
- `500` — Internal server error

---

[API](https://skmtc.net/uniclipboard/apis/uniclipboard-daemon-api.md) · [All operations](https://skmtc.net/uniclipboard/apis/uniclipboard-daemon-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/uniclipboard/uniclipboard-daemon-api/versions/a5d29889448a/schema)