Settings

See Domain Model → Settings for the three-layer resolution model (AppSettings → Settings → Application default) this resource implements.

1. Endpoints
2. GET /v1/users/{id}/settings
3. GET /v1/users/{id}/apps/{appId}/settings
4. PATCH /v1/users/{id}/apps/{appId}/settings

---

Endpoints

Method	Path	Purpose
GET	/v1/users/{id}/settings	Fetch global Settings.
PATCH	/v1/users/{id}/settings	Update global Settings.
GET	/v1/users/{id}/apps/{appId}/settings	Fetch the fully-resolved per-app settings.
PATCH	/v1/users/{id}/apps/{appId}/settings	Write per-app overrides.

GET /v1/users/{id}/settings

// Response — 200
{
  "user_id": "usr_01JAG3Z9X8QS3F6K2M4N5P6R7S",
  "locale": "en-US",
  "timezone": "America/Denver",
  "theme": "dark",
  "notifications": { "email": true, "sms": false },
  "updated_at": "2026-08-11T10:00:00Z"
}

Self, or a platform role with users.manage. The PATCH counterpart carries the same requirement.

GET /v1/users/{id}/apps/{appId}/settings

Returns the resolved object, plus the override layer that produced it:

// Response — 200
{
  "application_id": "app_timetrack",
  "resolved": {
    "locale": "en-US",
    "theme": "dark",
    "default_billable": true,
    "week_start": "monday"
  },
  "overrides": { "week_start": "monday" }
}

See Workflows → Settings resolution, in practice for exactly how resolved is computed. Caller may be the app itself (its own service API key), the user themselves, or an admin — the same model used by AppProfile.

PATCH /v1/users/{id}/apps/{appId}/settings

// Request — only the override being set
{ "overrides": { "week_start": "monday" } }

// Response — 200, same shape as the GET above, reflecting the new override

Validated against the target Application’s settings_schema (see Applications) — a key not declared in the schema, or a value of the wrong type, returns 422 with code: "settings_schema_violation" and the schema validation error in details. See Decisions → Settings schema ownership if this validation step turns out to be out of scope for the MVP.

To clear a single override back to inherited, send that key’s value as null:

{ "overrides": { "week_start": null } }