Application Settings & Devices

The Application Settings API is a generic per-user, per-app store for a client application's own settings, plus a device registry so those settings can follow the account across machines. It is the server side of the "Applications" feature: a native or web client (the first consumer is the Visual Introspection macOS app) reads and writes an opaque settings document, registers the machines it runs on, and resolves what a brand-new machine should start from on first run.

Every endpoint is authorized by Authorization: Bearer <sync-token> (or the web session cookie) and scoped to the authenticated user. No subscription is required. A token can only read and write its own user's documents; cross-user access is not possible.

Scopes: account vs device

Settings live in one of two scopes, both using the same document shape and the same optimistic-concurrency (compare-and-swap) rules:

• Account scope (shared): one document per app that follows the user across every machine. Path: /api/user/app-settings/{appKey}.
• Device scope (per-machine): one document per registered device, pinned to that machine. Path: /api/user/app-settings/{appKey}/devices/{deviceId}/settings. A device must be registered before its device-scoped document can be written.

The document is opaque to the server: it is stored and returned verbatim, byte for byte. Keys are never dropped, renamed, or reordered, even if a key is named like a secret (token, apiKey, and so on). The server does not interpret the payload and never logs it.

The settings document

Every read (and every successful write) returns a settings document with this shape:

Validation and limits

Reads are not rate-limited. The rate-limit bucket is keyed per user and per appKey, so writes to the account document, device documents, and the device registry for one app all draw from the same ~60/min budget.

Optimistic concurrency (compare-and-swap)

Writes to a settings document use body-baseVersion compare-and-swap so concurrent writers cannot silently overwrite each other:

• First-ever write: send baseVersion: 0. The server creates the document at version: 1.
• Update: send baseVersion equal to the document's current version. The server writes and increments version.
• Stale write: if baseVersion does not match (including sending a non-zero baseVersion when no document exists yet), the server returns 409 with the full current document under current, so the client can rebase and retry.

Error responses

Errors return the standard InterlinedList shape: a human-readable error string plus a stable machine-readable code.

{ "error": "Not found", "code": "not_found" }

Endpoint summary

Account-scoped settings

GET /api/user/app-settings/{appKey}

Auth required: yes Description: Read the account (shared) settings document.

Path parameters

Response 200 OK

{
  "appKey": "visual-introspection",
  "scope": "account",
  "deviceId": null,
  "version": 7,
  "updatedAt": "2026-08-15T18:04:22.000Z",
  "schemaVersion": 1,
  "settings": { "theme": "dark", "recentProjects": ["/a", "/b"] }
}

Error responses

PUT /api/user/app-settings/{appKey}

Auth required: yes Description: Create or update the account (shared) settings document using body-baseVersion compare-and-swap.

Path parameters

Request body

{
  "baseVersion": 7,
  "schemaVersion": 1,
  "settings": { "theme": "dark", "recentProjects": ["/a", "/b"] }
}

Response 200 OK: the newly stored document (with version incremented):

{
  "appKey": "visual-introspection",
  "scope": "account",
  "deviceId": null,
  "version": 8,
  "updatedAt": "2026-08-15T18:10:00.000Z",
  "schemaVersion": 1,
  "settings": { "theme": "dark", "recentProjects": ["/a", "/b"] }
}

Response 409 Conflict (baseVersion did not match):

{
  "error": "version_conflict",
  "code": "version_conflict",
  "current": {
    "appKey": "visual-introspection",
    "scope": "account",
    "deviceId": null,
    "version": 9,
    "updatedAt": "2026-08-15T18:12:00.000Z",
    "schemaVersion": 1,
    "settings": { "theme": "light" }
  }
}

current is the full current document. It is null in the rare case where a concurrent create won the race and the current row could not be re-read.

Error responses

DELETE /api/user/app-settings/{appKey}

Auth required: yes Description: Delete the account (shared) settings document. Idempotent.

Response 200 OK

{ "deleted": true }

deleted is true when a document was removed, false when there was nothing to delete.

Error responses

Device-scoped settings

GET /api/user/app-settings/{appKey}/devices/{deviceId}/settings

Auth required: yes Description: Read a device's settings document.

Path parameters

Response 200 OK

{
  "appKey": "visual-introspection",
  "scope": "device",
  "deviceId": "macbook-pro-9F2C1A7B4D",
  "version": 3,
  "updatedAt": "2026-08-15T18:04:22.000Z",
  "schemaVersion": 1,
  "settings": { "windowLayout": "split" }
}

Error responses

PUT /api/user/app-settings/{appKey}/devices/{deviceId}/settings

Auth required: yes Description: Create or update a device's settings document using body-baseVersion compare-and-swap. The device must be registered first (see register a device); a write to an unregistered device returns 404.

Request body (identical to the account PUT):

{
  "baseVersion": 3,
  "schemaVersion": 1,
  "settings": { "windowLayout": "split" }
}

Response 200 OK: the newly stored document with version incremented and scope: "device".

Response 409 Conflict: same shape as the account PUT, with current carrying the current device document.

Error responses

Device registry

Devices are the machines an app runs on. Each is identified by a client-stable deviceId that the client generates once and keeps (for example in the Keychain). The first device registered for an app becomes the default ("main workstation") automatically; its settings seed a brand-new machine on first run (see bootstrap).

GET /api/user/app-settings/{appKey}/devices

Auth required: yes Description: List the registered devices for this user and app, newest-seen first.

Response 200 OK

{
  "devices": [
    {
      "deviceId": "macbook-pro-9F2C1A7B4D",
      "deviceName": "Studio iMac",
      "platform": "macos",
      "isDefault": true,
      "lastSeenAt": "2026-08-15T18:04:22.000Z",
      "appVersion": "1.2.0",
      "osVersion": "15.5",
      "hasDeviceSettings": true
    }
  ]
}

Error responses

POST /api/user/app-settings/{appKey}/devices

Auth required: yes Description: Register a new device or refresh an existing one (keyed on deviceId). Registering an existing deviceId refreshes its name, platform, versions, and last-seen time while keeping its default flag. The first device registered for the app becomes the default automatically.

Request body

{
  "deviceId": "macbook-pro-9F2C1A7B4D",
  "deviceName": "Studio iMac",
  "platform": "macos",
  "appVersion": "1.2.0",
  "osVersion": "15.5",
  "appDisplayName": "Visual Introspection"
}

Response 200 OK

{
  "device": {
    "deviceId": "macbook-pro-9F2C1A7B4D",
    "deviceName": "Studio iMac",
    "platform": "macos",
    "isDefault": true,
    "lastSeenAt": "2026-08-15T18:04:22.000Z",
    "appVersion": "1.2.0",
    "osVersion": "15.5"
  }
}

The write response does not include hasDeviceSettings (only the list endpoint does).

Error responses

PATCH /api/user/app-settings/{appKey}/devices/{deviceId}

Auth required: yes Description: Rename a device and/or promote it to the default ("main workstation"). At least one of deviceName or isDefault must be present.

Request body

{ "deviceName": "Studio iMac", "isDefault": true }

Response 200 OK: the updated device (same shape as the POST response device object).

Error responses

DELETE /api/user/app-settings/{appKey}/devices/{deviceId}

Auth required: yes Description: Deregister a device and delete its device-scoped settings document. If the removed device was the default, the most recently seen remaining device is promoted to default automatically.

Response 200 OK

{ "deleted": true, "promotedDeviceId": "mac-mini-3B7E2F9A1C" }

Error responses

First-run bootstrap

GET /api/user/app-settings/{appKey}/bootstrap?deviceId={deviceId}

Auth required: yes Description: Resolve the settings a fresh machine should start from, with provenance. The client passes the new machine's deviceId and receives the resolved document plus a source describing where it came from, so it can seed itself and then PUT its own device document.

Query parameters

Resolution runs in priority order and returns the first that exists:

1. self: this device already has its own device document.
2. default-device: the default ("main workstation") device's document.
3. account: the shared account document.
4. none: nothing to seed from (returns 404).

Response 200 OK: the resolved settings document with a source field merged in at the top level (the document fields are not nested under a doc key):

{
  "source": "default-device",
  "appKey": "visual-introspection",
  "scope": "device",
  "deviceId": "mac-mini-3B7E2F9A1C",
  "version": 5,
  "updatedAt": "2026-08-15T18:04:22.000Z",
  "schemaVersion": 1,
  "settings": { "theme": "dark" },
  "defaultDeviceId": "mac-mini-3B7E2F9A1C",
  "defaultDeviceName": "Mac mini"
}

For source: "default-device", the response also includes defaultDeviceId and defaultDeviceName (the source machine). For source: "self" and source: "account", only source plus the document fields are returned. Note that scope and deviceId reflect the source document (for default-device they belong to the default machine, not the requesting deviceId).

Response 404 Not Found (nothing to seed from):

{ "source": "none" }

Error responses

Related

• Applications (Help Center): the user-facing guide to the Settings → Applications section.
• Authentication & OAuth: how to obtain and send the Bearer sync token.
• API overview: base URL, authentication at a glance, and response conventions.
• API explorer: try these endpoints live with the interactive Swagger console. </content>

</invoke>