Skip to content

User settings

Dashboard preferences of the logged-in user (theme, landing page, live view, notification and regional preferences). They are stored as one JSON document per user; missing keys are always filled in with the defaults below.

Defaults and allowed values:

Key Default Allowed values
theme light light, dark-blue, dark-black (an unknown value is saved as dark-blue)
accent blue blue, green, purple, orange, red (an unknown value is saved as blue)
landing_page home home, sensors, switches, gps, workstations, meteorological, batmon, ping, dynamic, shared-devices, alarms, reports, live (an unknown value is saved as home)
sidebar_collapsed false true, false
live.refresh 15000 Live page refresh interval in milliseconds
live.view All All, Grid, Table
live.sort status status, name, type, last_modified
notifications.email true true, false
notifications.sms false true, false
notifications.whatsapp false true, false
notifications.status_alerts true true, false
notifications.threshold_alerts true true, false
regional.time_offset 0 Offset from UTC in minutes, e.g. 120 for UTC+02:00
regional.unit_system metric metric, imperial
regional.date_format Y-m-d Y-m-d, d-m-Y, m-d-Y

Only theme, accent and landing_page are validated by the server; the other values are stored as sent. These are dashboard preferences: per-device alert switches are managed with Notifications.

Get settings

GET/user/settings

Returns the user's settings with every default filled in

Request

Auth: api_key (query param or cookie)

Request body:

None

Request example:

https://spoilerinterface.com/interface/user/settings?api_key=8f14e45fceea167a5a36dedd4bea2543

Response

{
    "success": {
        "theme": "light",
        "accent": "blue",
        "landing_page": "home",
        "live": {
            "refresh": 15000,
            "view": "All",
            "sort": "status"
        },
        "notifications": {
            "email": true,
            "sms": false,
            "whatsapp": false,
            "status_alerts": true,
            "threshold_alerts": true
        },
        "regional": {
            "time_offset": 0,
            "unit_system": "metric",
            "date_format": "Y-m-d"
        },
        "sidebar_collapsed": false
    }
}

An invalid api_key returns HTTP 401 with {"failed": "[Auth]: Failed to validate the api_key. Try to login again."}.

Update settings

POST/update/settings

Merges the submitted values into the user's settings, or resets them to the defaults

Request

Auth: api_key (query param or cookie) ยท Content-type: application/x-www-form-urlencoded

Request body:

The request body should be sent as form data. Only the submitted keys change; everything else keeps its current value.

  • Top-level keys are sent by name, e.g. theme=dark-blue.
  • Nested keys use dotted names, e.g. live.refresh=30000 or notifications.sms=true.
  • true / false are stored as booleans and whole numbers as integers.
  • Send reset=1 (alone) to restore all defaults.
Field name Description Type
theme [Optional] Theme str
accent [Optional] Accent colour str
landing_page [Optional] Page opened after login str
sidebar_collapsed [Optional] Collapse the sidebar bool
live.refresh / live.view / live.sort [Optional] Live page preferences int / str
notifications.* [Optional] Notification preferences (see table above) bool
regional.time_offset / regional.unit_system / regional.date_format [Optional] Regional preferences int / str
reset [Optional] 1 to reset to defaults str

Request example:

theme=dark-black&accent=green&landing_page=live&live.refresh=30000&notifications.sms=true

Response

The full, updated settings document:

{
    "success": {
        "theme": "dark-black",
        "accent": "green",
        "landing_page": "live",
        "live": {
            "refresh": 30000,
            "view": "All",
            "sort": "status"
        },
        "notifications": {
            "email": true,
            "sms": true,
            "whatsapp": false,
            "status_alerts": true,
            "threshold_alerts": true
        },
        "regional": {
            "time_offset": 0,
            "unit_system": "metric",
            "date_format": "Y-m-d"
        },
        "sidebar_collapsed": false
    }
}