Samna

Appearance

Settings ​

Settings is a free form JSON store keyed to a single user. It carries no schema and no business rules. It exists so frontends can persist user preferences and view state across sessions and devices without managing their own storage layer.

The shape inside value is owned by the application that writes it. The convention is to namespace top level keys by area so different parts of the application do not collide.

json
{
  "value": {
    "dashboard": { "info": [], "calendarsAndGraphs": [] },
    "calendar":  { "view": "week", "showWeekends": false },
    "bookings":  { "filters": {}, "sort": "starts_at" },
    "theme":     "dark"
  }
}

Operations ​

Read ​

GET /me/settings returns the calling user's settings. If no row exists yet the API returns an empty one, so a read always succeeds.

Replace ​

PUT /me/settings replaces value wholesale. Keys not in the request are lost. Use this when sending the complete settings state.

Merge ​

PATCH /me/settings deep merges the supplied value into the existing settings:

  • Top level keys in the request overwrite the same keyed values.
  • Top level keys absent from the request are preserved.
  • Nested objects merge recursively.
  • Arrays at any depth are replaced wholesale.

To add a single item to an array, read the current array first, mutate it, then write the full array back.

Both PUT and PATCH are also available at PUT /user/{id}/settings and PATCH /user/{id}/settings subject to access control.

API ​

The Settings tag covers read, replace and merge for the calling user and for a specified user.