Skip to main content
User preferences are a per-user, string-keyed store of raw JSON values backing UI settings — panel sizes, last-opened tabs, density, and the like. They follow the user across browsers, devices, and workspaces (preferences are never workspace-scoped), and the endpoints below let the frontend list, upsert, and delete individual keys. The handler is deliberately schemaless on the value side. The frontend writes whatever JSON shape it wants under a key; the server stores the bytes and hands them back unchanged on read. This keeps UI iteration fast — adding a new preference doesn’t need a migration or a backend release. Implementation: internal/api/user_preferences.go. Persisted in user_preferences (migration v58) as (user_id, pref_key, pref_value, updated_at) with a UNIQUE(user_id, pref_key) constraint.

​
Endpoints

MethodEndpointPurpose
GET/api/v1/me/preferencesList all preferences for the user
PUT/api/v1/me/preferences/{key}Upsert one preference key
DELETE/api/v1/me/preferences/{key}Delete one preference key

​
Auth and limits

  • All endpoints require an authenticated session.
  • The user_id is taken from the session — never from request bodies or query parameters.
  • Key constraint: [a-zA-Z0-9._-]{1,64}. Anything else returns 400. Keys land in URL paths, so this is a defensive parse before they reach the SQL layer.
  • Value cap: 16 KB per key. Larger payloads return 413 Request Entity Too Large.
  • There is no admin endpoint to read another user’s preferences.

​
List preferences

GET /api/v1/me/preferences
Returns every preference row for the authenticated user as a flat map of key → JSON value. Missing keys are simply absent from the map; the frontend falls back to its compiled-in defaults. Response: 200 OK 
{
  "ui.density": "comfortable",
  "ui.theme": "system",
  "crews.bottom_panel_height": 220,
  "chat.composer.send_on_enter": true,
  "chat.last_session_per_agent": {
    "agt_viktor": "cht_a1b2",
    "agt_eva": "cht_c3d4"
  }
}
Values are parsed JSON — a number stays a number, an object stays an object. The handler round-trips through json.RawMessage so the FE doesn’t have to JSON-decode each value separately. Errors:
StatusCondition
401Not authenticated.
500DB error or invalid JSON in a stored row (corruption — should not happen).

​
Set one preference

PUT /api/v1/me/preferences/{key}
Content-Type: application/json
Upserts one key. The request body is the raw JSON value to store — not a {value: …} wrapper. So setting ui.theme to "dark" is: 
PUT /api/v1/me/preferences/ui.theme
Content-Type: application/json

"dark"
And setting crews.bottom_panel_height: 
PUT /api/v1/me/preferences/crews.bottom_panel_height
Content-Type: application/json

220
Response: 204 No Content on success. Errors:
StatusCondition
400Invalid key (regex), or empty body.
401Not authenticated.
413Body exceeds the 16 KB cap.
500DB error.
The PUT is atomic via SQLite UPSERT (INSERT … ON CONFLICT(user_id, pref_key) DO UPDATE), so concurrent writes from two devices don’t lose data — last write wins.

​
Delete one preference

DELETE /api/v1/me/preferences/{key}
Removes the row for (user_id, key). Idempotent — deleting a non-existent key returns 204, not 404. The frontend’s “reset to default” action just deletes the key. Response: 204 No Content. Errors:
StatusCondition
400Invalid key.
401Not authenticated.
500DB error.

​
Conventional keys

The server does not enforce these names, but the frontend uses them consistently. Listing them here so integrators know what to read/write:
KeyTypePurpose
ui.themestring"light", "dark", or "system".
ui.densitystring"compact", "comfortable", or "spacious".
crews.bottom_panel_heightnumberPixel height of the bottom panel in /crews. First consumer of this table — the schema is intentionally generic so further preferences land without another migration.
chat.composer.send_on_enterboolIf false, Enter inserts newline and Cmd-Enter sends.
chat.last_session_per_agentobjectMap agentId → chatId so the chat surface re-opens the last session per agent.
Adding a new key is purely a frontend change — no API or migration work needed. Use the dotted-namespace convention (<surface>.<setting>) so a future grep stays scannable.