Atrium Gateway REST API

Returns immediately if the API service is up.

curl http://192.168.1.50/api/_health

{ "ok": true, "service": "atrium-api" }

Exchanges credentials for a session token. This is the same login the web interface uses, so any Atrium user account works.

Request body

curl -X POST http://192.168.1.50/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"ncdio","password":"your-password"}'

{
  "token": "e407a4ba1f73b881c6d7bc819e0e2f6e640b75a1ccabb35eb4c3c1de2dade81b",
  "username": "ncdio",
  "role": "admin",
  "allowed_pages": null,
  "enabled": true
}

Response fields

Error responses

Confirms a token is still valid and reports the account it belongs to. Useful as a cheap pre-flight after a long idle period.

{ "valid": true, "username": "ncdio", "role": "admin",
  "allowed_pages": null, "enabled": true }

Changes the authenticated account’s username and/or password. Requires the current password.

{
  "current_password": "old-password",
  "new_password": "new-password",
  "new_username": "integrations"   // optional; omit to keep the username
}

Returns the gateway’s current clock. Use it to detect clock skew between your system and the gateway before building time-window queries — if the two disagree, a “last 15 minutes” query can silently return nothing.

{ "epoch_ms": 1788874900454, "iso": "2026-09-08T13:41:40.454Z" }

Lists all whitelisted sensors, newest-reporting first. Returns a bare JSON array, not a wrapper object.

Query parameters

curl -s "$GATEWAY/api/sensors?q=office&limit=50" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "device_id": "00:13:a2:00:42:41:65:28",
    "sensor_type": 1,
    "sensor_name": "1 - Temperature/Humidity",
    "firmware": 10,
    "last_seen_epoch": 1788874772898,
    "last_seen_utc": "2026-09-08T13:39:32.000Z",
    "last_rssi": 40,
    "last_battery_v": 3.29,
    "last_battery_pct": 99.64,
    "location": "Travis' Office",
    "asset": "Jesse's Desk",
    "name": "Travis Office Temperature/Humidity",
    "install_date": "2026-06-02",
    "report_interval": 600,
    "last_error": null,
    "last_error_ts": null,
    "first_seen_ts": 1788536218806,
    "is_online": true,
    "has_active_alert": false,
    "status": "healthy"
  }
]

The sensor object

How status is computed

Evaluated in this order, first match wins:

A single sensor, keyed by device_id. Returns the same object as the list endpoint, minus first_seen_ts and has_active_alert.

curl -s "$GATEWAY/api/sensors/00:13:a2:00:42:41:65:28" \
  -H "Authorization: Bearer $TOKEN"

Returns 404 with {"error":"Sensor not found"} for an unknown device ID.

Every sensor type present on this gateway with a count of devices, most common first. A cheap way to learn what hardware is deployed before iterating the full inventory.

[
  { "type": 111, "count": 449 },
  { "type": 115, "count": 209 },
  { "type": 1,   "count": 60  }
]

Health transitions for one sensor, newest first — the audit trail behind the current status. Useful for reliability reporting and for confirming an intermittent sensor really is intermittent.

Query parameters

[
  {
    "id": 4127,
    "device_id": "00:13:a2:00:42:41:65:28",
    "old_status": "healthy",
    "new_status": "offline",
    "reason": "no report within 2x interval",
    "ts": 1788861600000
  }
]

Lists the metric names this sensor has actually reported. Always call this before hard-coding metric names — the available metrics depend on sensor type, firmware, and configuration, not on a fixed catalog.

{
  "device_id": "00:13:a2:00:42:41:65:28",
  "metrics": ["battery_pct","battery_v","counter","humidity","rssi","temperature"]
}

Note that battery_pct, battery_v, rssi, and counter appear alongside the real measurements — the gateway stores sensor health as ordinary metrics, so you can trend battery life exactly like temperature.

Returns readings for one sensor, optionally filtered to a single metric and time window.

Query parameters

# 1. Current value of one metric
curl -s "$GATEWAY/api/sensors/$DEVICE/telemetry?metric=temperature&limit=1" \
  -H "Authorization: Bearer $TOKEN"

# 2. Everything new since the last time you polled (incremental — do this)
curl -s "$GATEWAY/api/sensors/$DEVICE/telemetry?metric=temperature&start_time=1788874000000&limit=5000" \
  -H "Authorization: Bearer $TOKEN"

# 3. A fixed historical window
curl -s "$GATEWAY/api/sensors/$DEVICE/telemetry?metric=temperature&start_time=1788790000000&end_time=1788876400000" \
  -H "Authorization: Bearer $TOKEN"

{
  "device_id": "00:13:a2:00:42:41:65:28",
  "metric": "temperature",
  "bucket_ms": null,
  "count": 3,
  "readings": [
    {
      "timestamp": 1788874772898,
      "device_id": "00:13:a2:00:42:41:65:28",
      "metric": "temperature",
      "value": 25.2,
      "counter": 14,
      "sensor_type": 1,
      "firmware": 10,
      "rssi": 40,
      "tags": "{\"nodeId\":0}"
    },
    {
      "timestamp": 1788874742279,
      "device_id": "00:13:a2:00:42:41:65:28",
      "metric": "temperature",
      "value": 25.26,
      "counter": 13,
      "sensor_type": 1,
      "firmware": 10,
      "rssi": 40,
      "tags": "{\"nodeId\":0}"
    }
  ]
}

The reading object

Bucketed aggregation

Passing bucket_ms switches the endpoint into an aggregating mode that groups readings into fixed time buckets and returns an average per bucket, plus min_v, max_v, and a sample count n. Accepted values are clamped to between 1 second and 24 hours, and the aggregated result is capped at 5000 buckets.

{
  "device_id": "00:13:a2:00:42:41:65:28",
  "metric": "temperature",
  "bucket_ms": 3600000,
  "count": 250,
  "readings": [
    {
      "timestamp": 1788867578278,   // bucket start (currently NOT aligned — see warning)
      "device_id": "00:13:a2:00:42:41:65:28",
      "metric": "temperature",
      "value": 24.71,               // mean of the bucket
      "min_v": 24.71,
      "max_v": 24.71,
      "n": 1,                       // samples in the bucket
      "counter": 35,
      "sensor_type": 1,
      "firmware": 10,
      "rssi": 40
    }
  ]
}

Note that bucketed results are ordered ascending by bucket, the opposite of raw results.

Lists stored raw vibration captures for a vibration sensor, newest first. Returns capture metadata — sample rate, sample count, full-scale range, temperature, RPM, and a confidence figure — not the waveform itself.

{
  "device_id": "00:13:a2:00:5a:00:00:07",
  "count": 1,
  "fft_readings": [
    { "id": 91, "timestamp": 1788870000000, "device_id": "00:13:a2:00:5a:00:00:07",
      "sensor_type": 110, "odr": 3200, "total_samples": 4096, "fsr": 16,
      "temperature": 31.4, "rpm": 1780, "fft_confidence": 0.93,
      "created_at": 1788870001200 }
  ]
}

Retrieves one stored capture by its id. To compute a spectrum from it, see Section 15.

The raw metadata row for one sensor. Returns {} if no metadata has ever been saved.

{
  "device_id": "00:13:a2:00:42:41:65:28",
  "location": "Travis' Office",
  "asset": "Jesse's Desk",
  "name": "Travis Office Temperature/Humidity",
  "install_date": "2026-06-02",
  "report_interval": 600,
  "offline_alert_enabled": 1,
  "offline_alert_emails": "travis@ncd.io"
}

Creates or replaces the metadata row and returns the merged result.

Request body

curl -s -X POST "$GATEWAY/api/sensors/$DEVICE/meta" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "location": "Plant 2 / Line 4",
        "asset": "PUMP-00417",
        "name": "Line 4 Feed Pump — Bearing",
        "install_date": "2026-06-02",
        "report_interval": 600,
        "offline_alert_enabled": true,
        "offline_alert_emails": "maintenance@example.com"
      }'

The response is the stored row, so you can confirm exactly what was persisted.

Custom display labels for this sensor’s metrics.

{ "labels": [ { "metric": "temperature", "label": "Bearing Temp" } ] }

Sets labels in bulk. Send {"labels":[{"metric":"...","label":"..."}]}. An empty-string label deletes that label.

The core metrics battery_pct, rssi, and counter cannot be relabeled; attempting it returns 400 with a per-item errors array.

Unit-conversion formulas configured for this sensor’s metrics. Important for integrators: these are applied by the web interface for display. Stored telemetry — and therefore what the API returns — is always unconverted. If a customer has configured a conversion, read it here and apply the same arithmetic so your figures match what they see on screen.

{
  "conversions": [
    { "metric": "temperature", "formula": "value * 9 / 5 + 32",
      "unit": "°F", "label": "Bearing Temp", "visible": true }
  ]
}

The formula is a JavaScript expression in a single variable, value.

Sets conversions in bulk via {"conversions":[…]}. Each formula is validated by evaluation against sample inputs before it is stored, so a malformed expression is rejected with 400 rather than silently breaking the customer’s dashboard. Core metrics cannot be converted.

The operator’s preferred chart ordering for this sensor’s metrics, as an array of metric names. Purely a display preference.

Sets it. Body is {"order":["temperature","humidity"]}; maximum 100 entries.

Lists all synthetic variables as {synthetic_variables:[…], count}. Each carries id, name, formula, unit, label, and its inputs array.

One synthetic variable. 404 if unknown.

Creates one. Requires name, formula, and a non-empty inputs array in which every entry has var, device_id, and metric. The formula is validated before saving. Returns 201 with the generated id.

{
  "name": "supply_return_delta",
  "formula": "supply - return_",
  "unit": "°C",
  "label": "Supply/Return Δ",
  "inputs": [
    { "var": "supply",  "device_id": "00:13:a2:00:42:41:65:28", "metric": "temperature" },
    { "var": "return_", "device_id": "00:13:a2:00:42:41:65:99", "metric": "temperature" }
  ]
}

Read the resulting values back from the readings table using device ID synthetic and the variable’s name as the metric.

Dry-runs a formula against literal values without saving anything. Body is {"formula":"a+b","inputs":[{"var":"a","value":1},{"var":"b","value":2}]}; returns {"ok":true,"result":3,…}, or 400 with the evaluation error.

Deletes the variable and purges its computed readings. Not reversible.

Lists devices on one side of the whitelist.

Query parameters

[
  { "device_id": "00:13:a2:00:42:38:62:c6", "sensor_type": 115,
    "sensor_name": null, "is_whitelisted": false, "last_seen_ts": 1780690645050 }
]

Whitelists or un-whitelists a single device. Body is {"is_whitelisted": true}. Anything other than boolean true is treated as false.

Whitelists or un-whitelists many devices at once — the efficient way to commission a batch of sensors.

{
  "device_ids": ["00:13:a2:00:42:41:65:28", "00:13:a2:00:42:41:65:99"],
  "is_whitelisted": true
}

Returns {"ok":true,"updated_count":2,"is_whitelisted":true}. An empty or missing array returns 400.

Removes devices and all associated data — every reading, raw ingest row, metadata row, and alert condition — in a single transaction.

Body is {"device_ids":[…]}; returns {"ok":true,"deleted_count":n}.

Deletes all telemetry, devices, metadata, and alert rules, then compacts the database. Configuration, users, and sessions survive.

The alert event log, newest first. This is the endpoint to poll for CMMS work-order creation.

Query parameters

curl -s "$GATEWAY/api/alerts/history?limit=50" \
  -H "Authorization: Bearer $TOKEN"

{
  "history": [
    {
      "id": 338,
      "device_id": "00:13:a2:00:42:41:65:28",
      "sensor_name": "Temperature/Humidity",
      "metric": "automation",
      "alert_type": "automation",
      "event_type": "triggered",
      "value": null,
      "threshold_value": null,
      "condition": "High Temperature Alarm Email",
      "timestamp": 1788190592479,
      "recipient_email": "travis@ncd.io",
      "created_at": 1788190592000,
      "sensor_type": 1
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0,
  "search": null
}

The alert-history object

Current alert-rule state — one row per rule condition, with active rules first. This is a state view (“what is wrong right now”), where alert history is an event view (“what happened”).

{
  "alerts": [
    { "id": 12, "device_id": "00:13:a2:00:42:41:65:28",
      "sensor_name": "Travis Office Temperature/Humidity",
      "metric": "temperature", "threshold_value": 30, "condition": "above",
      "swing_value": 1.0, "recipient_email": null,
      "alert_active": true, "enabled": true, "created_at": 1780499419019 }
  ],
  "count": 1
}

An empty fleet returns {"alerts":[],"count":0}.

Threshold rules scoped to one sensor, including live alert_active state and the email recipients attached to each rule.

{
  "device_id": "00:13:a2:00:42:41:65:28",
  "thresholds": [
    { "id": 12, "device_id": "00:13:a2:00:42:41:65:28", "metric": "temperature",
      "threshold_value": 30, "condition": "above", "enabled": true,
      "swing_value": 1.0, "alert_active": false,
      "last_alert_time": null, "created_at": 1780499419019,
      "recipient_email": "maintenance@example.com" }
  ]
}

Creates or replaces a simple threshold on one metric.

Request body

Deletes an alert rule by ID. Despite the legacy path name, :threshold_id is an alert-rule ID — the id from GET /api/alerts. Returns {"ok":true,"deleted_id":n}.

All templates, each annotated with matched_device_count so you can see the blast radius before changing one.

{
  "templates": [
    { "id": 3, "name": "Cold room over-temp",
      "match_type": "location", "match_value": "Cold Room A",
      "metric": "temperature", "threshold_value": 8, "condition": "above",
      "swing_value": 0.5, "recipient_email": "ops@example.com",
      "enabled": true, "matched_device_count": 12,
      "created_at": 1780499419019, "updated_at": 1788190592479 }
  ],
  "count": 1
}

Previews which devices a match rule would cover, without creating anything. Call this before POSTing a template.

curl -s "$GATEWAY/api/alert-templates/match-preview?match_type=location&match_value=Cold%20Room%20A" \
  -H "Authorization: Bearer $TOKEN"

Returns {"devices":[{device_id, sensor_name, sensor_type, display_name, location, asset}], "count":n}.

Creates a template. Requires name, match_type, metric, and threshold_value; match_value is required unless match_type is all. condition defaults to above, swing_value to 1.0. Returns 201.

Partial update — send only the fields you want changed.

Deletes a template. Returns {"ok":true,"deleted_id":n}.

All triggers, each enriched with the sensor’s display name and its current live value for that metric — so one call tells you both the rule and how close it is to firing.

{
  "triggers": [
    { "id": 14, "name": "High Temperature Alarm",
      "device_id": "00:13:a2:00:42:41:65:28", "metric": "temperature",
      "threshold_value": 23.888424038887024, "condition": "above",
      "swing_value": 1, "condition_met": true, "enabled": true,
      "sensor_display_name": "Travis Office Temperature/Humidity",
      "current_value": 25.2,
      "created_at": 1780499419019, "updated_at": 1788190592479 }
  ],
  "count": 1
}

condition_met is the live evaluated state, including hysteresis — not a recomputation of current_value against threshold_value. Trust condition_met.

Creates a trigger. Requires name, device_id, metric, and threshold_value. condition defaults to above (any value other than below becomes above), swing_value to 1.0. Returns 201.

{
  "name": "Bearing over-temp",
  "device_id": "00:13:a2:00:42:41:65:28",
  "metric": "temperature",
  "threshold_value": 85,
  "condition": "above",
  "swing_value": 2
}

Partial update of name, threshold_value, condition, swing_value, or enabled. Note that device_id and metric cannot be changed — delete and recreate to re-point a trigger.

Deletes a trigger.

All automations with their triggers and actions nested inline — a complete picture of the customer’s alerting logic in one call.

{
  "automations": [
    {
      "id": 13,
      "name": "High Temperature Alarm Email",
      "logic": "AND",
      "enabled": true,
      "active": true,
      "last_triggered_time": 1788190592479,
      "created_at": 1780499419019,
      "updated_at": 1788190592479,
      "triggers": [
        { "id": 14, "name": "High Temperature Alarm",
          "device_id": "00:13:a2:00:42:41:65:28", "metric": "temperature",
          "threshold_value": 23.888424038887024, "condition": "above",
          "swing_value": 1, "condition_met": true,
          "sensor_display_name": "Travis Office Temperature/Humidity" }
      ],
      "actions": [
        { "id": 13, "action_type": "email",
          "config": { "recipients": "travis@ncd.io", "subject": "", "body": "" },
          "enabled": true, "fires_on": "trigger" }
      ]
    }
  ]
}

Creates an automation from existing triggers. Requires name, a non-empty trigger_ids array, and a non-empty actions array. Returns 201 with the new id.

{
  "name": "Bearing over-temp → maintenance",
  "trigger_ids": [14],
  "actions": [
    { "action_type": "email",
      "config": { "recipients": "maintenance@example.com",
                  "subject": "Bearing over-temperature",
                  "body": "" },
      "fires_on": "trigger" }
  ]
}

Updates an automation. Supplying trigger_ids or actions replaces the existing sets rather than adding to them.

Deletes an automation. Its triggers survive and can be reused.

The retained current value for every (topic, entity) pair — “what does the bus believe right now”. Filter with topic, source, or a free-text q.

{
  "state": [
    { "topic": "atrium/alert", "entity_key": "00:13:a2:00:42:41:65:28:temperature",
      "source": "atrium", "seq": 8814, "ts": 1788190592479,
      "payload": { "kind": "threshold", "state": "triggered", "active": true,
                   "device_id": "00:13:a2:00:42:41:65:28",
                   "metric": "temperature", "value": 25.2, "threshold": 23.88,
                   "condition": "above" } }
  ],
  "count": 1
}

The recent event log, newest first. Roughly a week of traffic is retained.

Each event carries seq, topic, entity_key, source, a parsed payload object, ts, origin, and delivered.

Everything wireable on this gateway: sources, publishable events with their payload schemas, and invocable actions. This is how you discover what the installed apps expose without reading their manifests.

Configured event→action bindings. Filter by source_topic or target_app.

One binding, plus its per-entity match state and its 50 most recent dispatch runs — the first place to look when a customer says an automation “didn’t fire”.

Creates a binding. Requires name, a source_topic of the form <source>/<name>, and target_kind of app or email; app additionally requires target_app and target_action. fires_on is enter, exit, or both (default). match, params, and clear_params are JSON. Returns 201 with the created binding.

Partial update. Re-enabling or re-pointing a binding also clears its failure counter and circuit breaker.

Deletes a binding; its state and run history cascade away with it.

Dispatch history across all bindings. Filter by binding_id, ok (true/false), edge (enter/exit/manual), since, and free-text q; limit defaults to 100, capped at 500.

Publishes a diagnostic event into the atrium namespace. Body is {"topic":"my-event","key":"entity-1","payload":{…}}; topic must be an unqualified name and is published as atrium/<topic>.

This lets an external system inject an event that the customer can then wire to an Atrium action — the one place the API can push into gateway logic. Delivery is asynchronous, handled by the daemon within about a second.

Broker counters plus which declared actions are actually bound. The answer to “why is my binding reporting action not available“.

Dispatches a binding immediately against its current retained state, bypassing the circuit breaker — an end-to-end wiring test. Body may set {"edge":"exit"}; the default is enter.

The full configuration as a flat key/value object. Call this first in any integration — it tells you the platform version and hardware model, which determine which endpoints exist.

{
  "gateway_name": "Gateway-D8FC",
  "platform_version": "2.5.3",
  "gateway_model": "EG5120",
  "display_timezone": "America/Chicago",
  "data_retention_days": "30",
  "temperature_unit": "C",
  "dashboard_refresh_interval": "30",
  "new_sensor_handling": "whitelist",
  "default_home_page": "/sensors",
  "remote_access_enabled": true,
  "remote_access_provisioned": true,
  "remote_access_hostname": "d8fc.iolight.com",
  "nodered_enabled": false,
  "proxy_enabled": false,
  "proxy_scheme": "http",
  "proxy_auth_type": "none"
}

Keys worth knowing

Writes the settings keys. gateway_name is required on every call; omitting it returns 400.

Toggling remote_access_enabled starts or stops the tunnel immediately. If the unit was never provisioned, the response includes a warning and the setting is stored but has no effect.

Admin username plus viewer-account state. Admin only — a viewer token gets 403 {"error":"Admin access required"}.

{
  "admin_username": "ncdio",
  "viewer": { "exists": true, "username": "integrations",
              "enabled": true, "allowed_pages": ["/sensors","/monitor"] }
}

Creates or updates the single viewer account — the recommended way to provision a dedicated login for an integration. Admin only.

{
  "username": "integrations",
  "password": "a-strong-unique-password",
  "enabled": true,
  "allowed_pages": ["/sensors", "/monitor"]
}

• A blank password preserves the existing one, so you can change grants without knowing it.
• A password is required when creating the account for the first time.
• The viewer username must differ from the admin’s.
• Setting enabled: false immediately invalidates that account’s active tokens.

Removes the viewer account and its sessions. Admin only.

Queries the release repository and caches the result. Returns {"ok":true,"update_available":bool,"available_version":string|null}. A transient network failure still returns 200 with ok:false and an error string, so branch on ok rather than on the status code.

Applies the update found by the last check. Returns immediately with {"ok":true,"status":"running"}; the work happens in the background. 400 if no update is pending.

Installs a specific version regardless of what the check found. Body is {"version":"2.5.3"}; required. Returns 404 if no such release or package exists.

Poll this during an update. Returns {step, message, percent, status, timestamp}, with status of idle, running, or error. When nothing is running you get {"step":"none","status":"idle","percent":0}.

Returns {package, installed_version, latest_version, update_available, last_checked, updating, progress}.

Queries the npm registry for the newest published version and caches it. Like the firmware check, registry failures return 200 with ok:false.

Installs a version — {"version":"2.0.4"}, or the cached latest if omitted — then restarts the ingest daemon. Returns 409 if an update is already running, 400 for a malformed version or when nothing is cached.

Because this restarts the daemon, the radio stops briefly and radio-coupled endpoints will fail for a few seconds.

Progress of an in-flight library update, in the same shape as the firmware progress endpoint.

Sends a single test email using credentials supplied in the body, without saving them. Returns 200 on success; 400 for a validation failure and 500 for a send failure, with a stage field indicating where it went wrong.

Outbound HTTP proxy settings, for gateways behind a corporate proxy. Secrets are never returned — instead you get has_password, has_client_cert, has_client_key, and has_ca_cert booleans.

Saves proxy settings. When proxy_enabled is true, proxy_host is required and proxy_port must be 1–65535. Any supplied PEM material is validated before it is persisted. Supports none, basic, and digest authentication, plus client certificates.

Tests a proxy configuration before committing it, optionally against your own test_url. Returns the observed HTTP status and a stage on failure.

Returns {enabled, running, registered, status}, separating the user’s intent (enabled) from live process state.

Body {"enabled": true|false}. Starts or removes the process and persists the choice across reboots. Once running, the Node-RED editor is on port 1880.

Complete network state — interfaces, addresses, cellular, NTP, and the available timezone list. Read-only and always safe.

On a gateway that cannot report (helper not installed) it returns 200 with {"ok":true,"available":false,"code":"helper_missing"} rather than an error, so treat available as the gate. On an EG5100, cellular is null and cellular_supported is false — that is the hardware fact, not a missing configuration.

Confirms a pending network change, cancelling the rollback. Returns {"ok":true,"confirmed":true}. Takes no body.

Sets the IPv4 configuration of one interface. Requires target (wifi or ethernet) and connection_type (dhcp or manual); a manual configuration also takes address, gateway, dns1, and dns2. Arms the watchdog.

Sets the LAN address and DHCP server pool: address, dhcp_enable, pool_start, pool_end, dns1, dns2, lease_time. Subnet and pool arithmetic is validated before anything is applied. Always requires the watchdog.

Current WiFi mode, SSID, link state, IP, and the reason for any previous rollback. Also reports watchdog — if false, a client-mode switch will be refused.

Scans for visible networks and returns {"ok":true,"networks":[…]}. Takes up to 30 seconds — set your client timeout accordingly.

Switches WiFi mode. Requires mode of ap or client; client mode also takes ssid, password, security, hidden, and bssid. A client switch requires the watchdog, so a wrong password reverts to the access point instead of stranding the unit.

Configures the cellular modem: primary_sim (sim1/sim2), apn, username, password, auth_type (none/chap/pap), and optional extra_at_cmd. A username is required when authentication is CHAP or PAP.

EG5120 only. On an EG5100 this returns 403 with {"code":"unsupported_hardware"} — enforced server-side, not merely hidden in the UI.

Sets time synchronization: primary_server, optional secondary_server, and timezone. Servers must be a hostname or IPv4 address.

The configuration schema for a sensor type — every option, its valid range, and its meaning. Call this before attempting to write a sensor configuration, so you send only fields the hardware accepts.

Returns 400 with an error string for a type the sensor library does not recognize.

One sensor’s configuration: reported_configs (what the sensor last told us), desired_configs (what is queued for it), plus report_interval_info explaining the expected cadence and diagnostics for read-only counters. A device that has never checked in returns {"reported_configs":{},"desired_configs":{}}.

Diagnostic values arrive on the sensor’s check-in packet rather than with telemetry, so they refresh on the sync interval (default one hour). Present them as “as of last check-in”, not as live values.

Queues a configuration change. The body is an array, not an object: [{"addr":"<device_id>","configs":{…},"type":<sensor_type>}].

The whole mesh as {nodes, edges, routes} — a graph you can render directly. Nodes carry a role of gateway, repeater, or sensor plus their hop depth; edges carry link-test results including retry counts and min/max/average RSSI. A pure database read, safe to poll.

The stored route for one sensor: status, route array, hop_count, and timing. Returns {"exists":false,"device_id":"…"} if no mapping has ever been requested.

Queues a route-discovery request. Returns {"success":true,"device_id":"…","status":"pending"}. Poll the GET above for the result.

Flags a one-shot raw vibration capture, transmitted on the sensor’s next check-in. Body may set {"probe":"1"}. Returns {"success":true,"device_id":"…","probe":"1","status":"pending"}.

Runs spectral analysis on a stored capture and returns the computed spectrum. No radio involved — it processes data already on the gateway — but it is CPU-intensive Python. On an EG5100 (single core, no swap) expect it to be slow and avoid running several at once. Returns 503 if the analysis subsystem is unavailable.

Registered peers as an array of {address, name, notes, enabled, created_at, updated_at}.

Registers a peer. address is required — a 64-bit DigiMesh MAC. Upper case and unseparated hex are accepted and normalized to lower-case colon form. Returns 201, or 409 if already registered, or 400 for a malformed address.

Updates name, notes, or enabled. 404 if unknown.

Removes a peer, revoking app authority to command it.

The caller’s views, ordered by position. A user with none gets a default “Dashboard” view created automatically, so this never returns an empty array.

Creates a view. name is required; position defaults to the end of the tab strip.

Renames or reorders a view via name and position.

Deletes a view and all its widgets. A user must always keep at least one view, so deleting the last returns 400.

The caller’s widgets, with config parsed into an object. Pass view_id to scope to one tab.

Creates a widget. widget_type is required and must be one of:

line_graph   metric_card   bar_chart   gauge   area_chart
sparkline    stat_card     table       tank_level

width is clamped to 1–4 (default 2) and height to 1–6 (default 2). config must be an object. If view_id is omitted the widget lands in the caller’s default view; a view_id the caller does not own returns 403.

Partial update. Setting view_id moves the widget to another of the caller’s views.

Deletes a widget.

All configured reports, with config parsed and last_sent populated.

Creates a report. name, report_type, schedule, and recipient_email are required.

An invalid report_type or schedule returns 400 listing the accepted values. Returns 201 on success.

Partial update. Sending no updatable fields returns 400.

Deletes a report.

Generates and emails a report immediately, ignoring its schedule — useful for verifying a report before trusting it to a schedule. Returns {"success":true,"id":n}, or 404 if the report is unknown or disabled.

This runs PDF generation synchronously, so it can take a while on constrained hardware. Set a generous client timeout.

Returns {queries:[{id, name, sql_text, created_at}], count}.

Creates one. name and sql_text are both required. Returns 201 with the new id.

Deletes one.

Installed apps with version, enabled state, declared capabilities, model support, and license status. Also returns gateway_model and gateway_id at the top level.

{
  "apps": [
    { "id": "machine-health", "name": "AssetPulse", "version": "1.4.2",
      "description": "Vibration-based machine health monitoring",
      "enabled": true, "model_supported": true, "available": true,
      "path": "/apps/machine-health", "ui": {},
      "capabilities": ["readings:read","events:publish"],
      "license": { "required": true, "state": "licensed", "reason": null,
                   "reason_text": null, "customer": "Example Mfg",
                   "expires_at": 1820000000000 } }
  ],
  "count": 1,
  "gateway_model": "EG5120",
  "gateway_id": "0013a200424165 28"
}

available is the field to check before calling an app’s endpoints: it is true only when the app is enabled, supported on this hardware, and licensed. A license.state of unlicensed means the app’s routes return 402.

License status for one app, including the gateway ID a license must be bound to. 404 if the app is not installed.

Activates a license. Body is {"license":"<token>"} (token is accepted as an alias). The license is verified against this gateway before being saved, so a license issued for another unit is rejected with 400 and a machine-readable reason. On success both services restart.

409 means the gateway ID is not yet known because the radio has not reported in — retry shortly.

Removes a stored license and restarts services. Intended for support and testing.

Installs a signed app package uploaded as raw bytes — Content-Type: application/gzip or application/octet-stream, up to 200 MB. Optional query parameters expect_id pins the target app and allow_downgrade=1 permits installing an older version.

Uninstalls an app and restarts services. Returns {"ok":true,"id":"…","purged_data":bool,"restarting":true}. Purging also deletes the app’s database.

Enables an app. Revokes its existing scoped tokens and restarts services. 404 if not installed.

Disables an app without uninstalling it. Same token revocation and restart.

Mints a scoped token for an app’s sandboxed UI. Returns {token, expires_at, capabilities}.

The App Center catalog, annotated with what is installed and what this gateway can run. Pass refresh=1 to bypass the cache. If the catalog is unreachable you still get 200, with unavailable:true and an error string.

One catalog app in detail: all versions with their platform and model requirements, release dates, sizes, changelogs, an install_blocked_reason per version, and the README as sanitized HTML or raw markdown.

Downloads and installs an app by ID. Body is {"id":"machine-health","allow_downgrade":false}. Returns 502 if the App Center is unreachable.

Static frontend assets for an installed app’s UI. Unauthenticated, exactly as nginx would serve any static bundle — the app’s data still requires a token. Not useful to an integration; documented for completeness.

Lists table names: {"tables":["readings","devices",…]}.

Column definitions for one table. table is a required query parameter and must be a valid identifier; anything else returns 400. Each column reports cid, name, type, notnull, dflt_value, and pk.

Executes a statement. Body is {"query":"SELECT …"}. A SELECT returns rows; a non-returning statement executes and yields an empty rows array. A SQL error returns 400 with the engine’s message.

curl -s -X POST "$GATEWAY/api/sqlite/query" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query":"SELECT (ts/86400000)*86400000 AS day, AVG(value) AS avg_c, MIN(value) AS min_c, MAX(value) AS max_c, COUNT(*) AS n FROM readings WHERE device_id = '\''00:13:a2:00:42:41:65:28'\'' AND metric = '\''temperature'\'' GROUP BY day ORDER BY day DESC LIMIT 30"}'

{
  "success": true,
  "rows": [
    { "day": 1788872400000, "avg_c": 24.93, "min_c": 24.1, "max_c": 25.8, "n": 86 }
  ],
  "count": 1,
  "query": "SELECT (ts/86400000)*86400000 AS day, …"
}

Tables you are most likely to want

Whether Atrium publishing is on, the resolved topic paths, and the publisher grant list. Verified live:

{
  "publishing_enabled": false,
  "topics": [
    "Article_Channel/Gateway-D8FC/telemetry/<device_id>",
    "Article_Channel/Gateway-D8FC/alerts/<device_id>",
    "Article_Channel/Gateway-D8FC/status/<device_id>"
  ],
  "publishers": [
    { "id": "atrium", "name": "Atrium (sensor telemetry, alerts & status)",
      "granted": false }
  ]
}

The resolved topics array is the quickest way to confirm exactly what to subscribe to — the placeholders are already substituted. The gateway above has a custom prefix (Article_Channel/) configured ahead of the default pattern, which is why its topics are longer than the defaults listed earlier — another reason to read the resolved list rather than assume the default.

Broker settings. The password is returned masked, never in clear text, and certificate material is reported only as has_ca_cert, has_client_cert, has_client_key booleans.

Saves broker settings and reconnects immediately. host is required and must be a valid hostname; port must be 1–65535. Topic patterns are validated. PEM material is checked before it is stored.

Submitting a blank password — or the mask returned by GET — preserves the stored password, so you can change topics without knowing the credential.

Sets the publisher grant list — the switch that actually starts the sensor-data feed. Grant atrium to enable automatic publishing.

Turns publishing on or off without discarding the broker configuration.

Publishes one message immediately, bypassing the grant list — the fastest way to prove host, port, credentials, and TLS are correct before enabling the real feed. A broker host must be saved first.