BluNotify Partner API — Guide

Overview

Base URL: https://api.blunotify.com. All requests and responses are JSON. Every endpoint is under /v1 and requires authentication. HTTPS is mandatory. A machine-readable description is available at /openapi.json, and the reference lists every route, parameter and field from it, with example requests and responses. This page is the guide: what the API is for, how scope, permissions and limits work, and what to watch for. Every response carries an X-Request-Id header; quote it when you contact BluNotify support (see Error codes).

Authentication

Authenticate with a bearer API key issued by BluNotify staff:

Authorization: Bearer bnp_3f8a2c91d0_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Keys look like bnp_<handle>_<secret>. Only the bnp_<handle> prefix is ever shown in dashboards or logs; the secret is shown once at creation and stored only as a hash.
• Receiving a key: BluNotify usually sends a one-time link, and a 6-digit passcode separately by text or phone. Open the link and press Show my key: the key is created at that moment and shown only to you, once. Store it straight in your secrets manager. If the page says the link was already used and it wasn't you, tell your BluNotify contact so that key can be revoked.
• Rotation: a partner can hold several active keys at once. To rotate, request a new key, switch your client to it, then have the old one revoked.
• Revocation takes effect immediately on the next request.
• A missing, malformed, unknown, or revoked key returns 401 with a single generic message — the API never reveals which keys exist.

Permissions

Each partner has explicit permission flags, grouped into the same categories BluNotify staff see when granting them. Your effective permissions are visible at GET /v1/account (as a flat map — the grouping below is purely for reading this reference). Under each flag's name below is its key in that map, which is also how a 403 names a permission you are missing (required_permission).

General device management

Product-independent: these gate the same routes for every device in your scope.

BluNotify — alerting devices

BluEM — energy monitors

Device scope

Every flag above is independent — none is implied by any other. A request that lacks the required flag, targets a device outside your scope, or targets a channel you aren't permitted returns 403 (or 404 for an out-of-scope device).

When a request is refused because your key lacks a flag it needs, the 403 body names the flag in required_permission, by its GET /v1/account key: that is the permission to ask BluNotify staff for. Flags are checked before the rest of the request, so with the flag granted the same request can still be refused for something else, such as a channel outside your list or a bad parameter. A 403 that no permission would lift — that channel, a setting that cannot be written — names none, and neither does a 404.

403 {"error":"energy data access not permitted","code":"forbidden",
     "required_permission":"energy_read","request_id":"req_5f0c2a9e41b7d3c8a6e1f204"}

Devices & channels

You can only see and control devices in your scope. A device is in scope if it sits inside an organization subtree granted to you (see Organization scoping), or your account has the Access ALL devices scope flag — those are the only two sources of reach. Out-of-scope devices always return 404, indistinguishable from nonexistent ones. Each device exposes up to five channels:

Your allowed channels are configured per partner, across your whole scope. GET /v1/devices lists your devices, which product each one is, and, on a BluNotify device, its permitted channels. A BluEM energy monitor has no channels.

Endpoints

Your partner name, permissions, allowed channels, and rate limits.

Devices in your scope, in device-id order. Each: device_id, name, product (blunotify for a notification light, bluem for an energy monitor), and — only on a BluNotify device — channels and automation_enabled; and, only if you have health read, the connectivity fields status, status_changed_at and last_seen_at. Pass ?product=bluem (or blunotify) to list one product's devices; an unknown value is a 400, never an empty list.

{"devices":[
  {"device_id":"7C9EBD91235C","name":"Walk-in freezer","product":"bluem"},
  {"device_id":"F8B3B7229080","name":"Front desk","product":"blunotify",
   "channels":["light2","light3","sound"],"automation_enabled":true}]}

A single device in your scope, with the same fields as in the list.

Predefined commands available to you, with each parameter's min/max/default after your limits. This is the authoritative parameter reference for your account.

Provision a new device under the firmware's derived-v1 credential contract, and place it in your scope. Requires the device-provisioning permission. The device ID is not yours to choose — it is the ESP32 base MAC as exactly 12 uppercase hexadecimal characters, no separators (^[0-9A-F]{12}$). That one string is the MQTT username, the HKDF salt, and the firmware device ID; anything else is a 400. It must not already be in use.

Every device holds a 16-character root secret in its one-time-programmable ESP32 eFuse, and its 32-character MQTT broker password is derived from that secret (HKDF-SHA256, salt = the device ID, label = <product>/mqtt/v1) rather than being an independent random string. The server stores only the derived MQTT password — never the root secret.

Placement (org)

What org may be, and whether it is required, depends on your account's scope:

For an org-scoped partner, a name that names no node at all and a name that names a real node outside your granted subtrees get the identical answer — 400 "unknown organization '<org>'" — so the response never confirms or denies the existence of an organization you cannot see. A name that matches more than one node inside your own scope is refused instead as 400 "organization '<org>' is ambiguous: N organizations in your scope share that name" — that answer only describes your own granted forest, already visible via GET /v1/org-tree.

# virgin device: the server mints the root secret and derives the password
curl -X POST https://api.blunotify.com/v1/devices/7C9EBD911E74 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"credential_format":"derived-v1","name":"Front Desk Light"}'

201 Location: /v1/devices/7C9EBD911E74
{"device_id":"7C9EBD911E74","credential_format":"derived-v1",
 "product":"blunotify","password":"Xq7mK2vD9tRb4Zs1","name":"Front Desk Light"}

# re-enrollment: the eFuse is already burned, so derive from the SAME secret
curl -X POST https://api.blunotify.com/v1/devices/7C9EBD911E74 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"credential_format":"derived-v1","credential_source":"root_secret",
       "root_secret":"Xq7mK2vD9tRb4Zs1"}'

201 {"device_id":"7C9EBD911E74","credential_format":"derived-v1","product":"blunotify"}

Remove a device: cuts its broker credential, then deletes its device record. Requires the device-removal permission. Applies to any device currently in your scope — not only ones you provisioned yourself (e.g. a demo device staff granted into your scope can also be removed if you hold this permission).

Confirmation is required. Pass confirm equal to the device id, either as a query parameter (shown below) or in a JSON body. Without it — or with a value naming a different device — the request is refused with 409 confirmation_required and nothing is deleted. Removal also spends a slot from the same per-hour destructive-operation ceiling as factory_reset, so a run of deletions is rate limited with 429.

curl -X DELETE "https://api.blunotify.com/v1/devices/front-desk-01?confirm=front-desk-01" \
  -H "Authorization: Bearer $KEY"

204 (no body)

Send a raw command. Requires the raw-command flag and channel access. Availability caps (minimum flash period, maximum overlay duration/interval, etc.) apply unless your account also has the relaxed-caps permission — the raw-command grammar itself is always enforced either way.

curl -X POST https://api.blunotify.com/v1/devices/DEV123/commands \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"channel":"light1","payload":"sldff0000"}'

202 {"channel":"light1","payload":"sldff0000"}

Trigger a predefined command with optional parameters. Requires the predefined flag, channel access, and that the command is granted to you.

curl -X POST https://api.blunotify.com/v1/devices/DEV123/channels/light2/effects \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"command":"flash_white","params":{"period_s":0.25,"duration_s":3,"interval_s":60}}'

202 {"command":"flash_white","channel":"light2","payload":"003000000060tglffffff000000025050"}

On light2/light3, effects are automatically wrapped as repeating overlays; pass duration_s (how long each occurrence lasts) and interval_s (how often it repeats). The payload field (the encoded wire-format string) is only included in the response if you also have raw-command access — otherwise the response omits it and returns just command and channel. Both routes answer 202 Accepted: the command was handed to the broker, which is all the API waits for.

Latest command per permitted channel, with a decoded label. Requires state read.

{"device_id":"DEV123","state":{"light1":{"payload":"sld00ff00","label":"Green (Solid)","updated_at":"2026-07-04T12:00:00+00:00"}}}

The raw payload field is only present if you also have raw-command access; without it, each channel returns just label and updated_at.

The connectivity fields and recent health telemetry. Requires health read. Query params: hours (default 24, max 720) and limit (max 500).

{"device_id":"DEV123","status":"connected","status_changed_at":"2026-09-27T14:02:11+00:00",
 "last_seen_at":"2026-09-27T15:40:03+00:00",
 "telemetry":[{"created_at":"…","topic":"…","payload":"…"}]}

Connectivity fields

Enable/disable temperature-sensor automation for a device. Requires the automation-control permission (an independent add-on).

curl -X PUT https://api.blunotify.com/v1/devices/DEV123/automation \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"enabled":false}'

{"device_id":"DEV123","automation_enabled":false}

Command parameters

Parameterized effects accept fields such as period_s, duty_ratio, brightness_pct, duration_s, interval_s, and volume. Every value is validated against a configurable min/max; an out-of-range value is rejected (not clamped) with 400. Your exact allowed ranges are in GET /v1/commands. To protect device availability, the API also caps effect duration, minimum flash period, and repeat interval.

Requests and responses

• Bodies are JSON objects. Send them with Content-Type: application/json. Any other media type is 415 unsupported_media_type; a body that is not valid JSON, or is not an object, is 400 validation_error. Routes whose fields are all optional take no body at all.
• Nothing is cacheable. Every /v1 response carries Cache-Control: no-store: answers are yours alone, and some carry secrets.
• A 401 carries WWW-Authenticate: Bearer realm="BluNotify Partner API" (RFC 6750), with error="invalid_token" when a key was sent.
• Lists page with cursors. Wherever a list pages, pass the answer's next_cursor back as cursor; has_more says whether another page is waiting. Cursors are opaque and URL-safe.

Error codes

Errors are JSON: {"error":"…","code":"…","request_id":"…"}. code is the stable word to branch on; error is a sentence for people and may be reworded. New codes may be added, so handle one you do not know by its HTTP status. A 403 can also carry required_permission (see Permissions).

Request IDs. Every response carries an X-Request-Id header, and every error body the same value as request_id. Log it with your own error, and quote it when you contact BluNotify support: it finds your call in our records.

Rate limits

Limits apply per partner (requests/minute) and per device (commands/minute), plus a global per-device ceiling shared across partners. Configuration-API mutations (rename, org move, sensor changes, profile writes) share a separate per-partner throttle (default 30/minute). Destructive operations — destructive System-API verbs, connection/identity settings writes, and DELETE /v1/devices/{id} — additionally share one per-partner per-hour ceiling. Exceeding a limit returns 429 with a Retry-After header (seconds). Build in backoff and avoid tight retry loops.

Every response to a request with a valid key describes your per-partner request limit, so you can slow down before you reach it:

They describe the per-partner request limit only. The per-device and per-operation limits above answer with a 429 and Retry-After as before.

Retrying safely: Idempotency-Key

A request that times out may still have reached the device. To retry any POST without doing its work twice, send an Idempotency-Key header: a value you generate for that one request, such as a UUID, and send again unchanged on every retry of it.

curl -X POST https://api.blunotify.com/v1/bluem/devices/EM123/report \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: 5b0f7e2c-3a41-4d6e-9f3e-8c1d2b7a9e10"

A key belongs to your account and the route it was sent to: the same value on another route, or from another partner, is a different key. A key is kept for 24 hours; after that it is new again. A replay is the stored answer as it was: it is not checked again against your permissions or scope as they are now. A replay still counts against your request rate limit, but not against the device's command limits, because nothing is sent. The header is not taken by the platform file upload (POST /v1/system/files), which never overwrites a file, so a repeat is already refused with 409. For POST /v1/devices/{id} (provisioning), a replay returns the generated password again: the one way to recover it if the first response was lost.

POST /v1/devices/{id}/files also recognises a key it has seen for as long as the transfer exists, answering 200 with the transfer's current state once the 24 hours have passed.

Automation interaction & conflicts

Configuration API — device setup, org scoping, alert profiles & signals

The Configuration API lets a partner manage its fleet's setup the way BluNotify's own console does: rename devices, place them in an organization tree, attach temperature sensors (TDLs), and control which alert profile (rule document) each sensor is evaluated with. It is gated by three independent flags — config read, config write, and profile manage — and every call is audited. Config mutations share a separate per-partner rate limit (default 30/minute).

Organization scoping

Your reach is defined by exactly two sources, combined: BluNotify staff can grant your account one or more organization subtrees (any device attached to a node inside a granted subtree is in scope for you), and/or your account can hold the Access ALL devices scope flag (every device in the fleet, including future ones). There is no other way for a device to enter your scope — devices are no longer assigned to a partner individually. GET /v1/org-tree returns your granted subtrees as a forest (each granted root's parent_id is nulled); with the access-all-devices scope flag it returns the whole tree. No grants means an empty forest, not an error.

Your visible org nodes: {"nodes":[{"id","parent_id","name"}]}. Requires config read.

A device's configuration: device_id, name, org_node, its attached sensors (each with tdl_id, label, profile), automation_enabled, and alert_signal_id (the light's alert signal; null = the default). Requires config read.

Rename a device. Body: {"name"} (1–120 characters). Requires config write.

Move a device to an org node (or detach with null). Body: {"org_node_id"}. Requires config write. The target node must be inside your own granted scope (403 node_out_of_scope otherwise — you can never expand your reach). For an org-scoped partner (no Access ALL devices), org_node_id: null is always 409 would_lose_access: since a granted subtree is your only reach to the device, detaching it would strand your own access — only a partner with Access ALL devices may park a device back in Staging / Inventory this way.

Attach a sensor. Body: {"tdl_id", "profile_id"?} — tdl_id is 1–64 chars (letters, digits, _, -, ., :); profile_id must be a global or your own partner-owned profile (null = Default). 409 already_attached if the sensor is already on that device. Requires config write.

Change an attached sensor's alert profile. Body: {"profile_id"} (null clears to Default). Requires config write.

Detach a sensor from a device. Requires config write.

Alert profiles

An alert profile is an ordered rule document — first matching rule wins — that maps a sensor's recent readings to an alert level. Each rule is a set of conditions ({"metric", "op", "value"}) that must all hold. Metrics include reading_count, newest_age_secs, latest_breach, consecutive_breaches, breaches_in_window, latest_temp_c, latest_humidity, and the sensor's min_temp_c/max_temp_c thresholds; operators are ==, !=, <, <=, >, >=, is_null, not_null. Every document is validated server-side (≤20 rules, ≤8 conditions per rule) and rejected with 400 validation_error if malformed.

Profiles visible to you: global profiles plus your own partner-owned ones — each with id, name, scope, version, description, rules. Requires config read.

Create a partner-owned profile. Body: {"name", "rules", "default"?}. Requires profile manage. Capped at 50 profiles per partner (403 limit_reached); a duplicate name is 409 name_taken.

curl -X POST https://api.blunotify.com/v1/profiles \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Strict freezer",
       "rules":[{"all":[{"metric":"reading_count","op":"<","value":3}],"level":"INSUFFICENT_DATA"},
                {"all":[{"metric":"consecutive_breaches","op":">=","value":2}],"level":"WARNING"}],
       "default":"CLEAR"}'

201 Location: /v1/profiles/17
{"id":17}

Update one of your own profiles (name and/or rules). Global, system, and other partners' profiles return 404. Each update bumps the profile's version and records a revision. Requires profile manage. Note: the change takes effect everywhere the profile is assigned, on the next alert-evaluation cycle (~2 minutes).

Delete one of your own profiles. Refused with 409 in_use (including the sensor count) while any sensor still references it — reassign those sensors first. Requires profile manage.

Alert signals

An alert signal decides what a light shows (light1) for each alert state. It has four entries: CLEAR, ADVISORY, WARNING, and NO_DATA, which covers the four states where the temperature cannot be judged (NO_SENSORS, INSUFFICENT_DATA, STALE_DATA, UNKNOWN). A light with no signal of its own shows the default signal: solid green, solid amber, solid red, and pulsing blue. A change reaches a light at its next state change, or within the hour.

Each entry is {"light": {"type", …fields}}. Every field is required; a value outside its range is refused (400 validation_error, naming the entry and field), never rounded. Colours are {"r","g","b"} whole numbers 0–255. Periods are 0.1–9.999 s, animation times 0.1–99.999 s, width 1–12, duty ratios 0.01–0.99, and repeat_s a whole number of seconds 0–999999 (0 = play once; otherwise it must outlast the animation).

Signals visible to you: the global ones (including the default, marked is_default) plus your own — each with id, name, scope, is_default, version, description, entries. Requires config read.

Create a partner-owned signal. Body: {"name", "entries", "description"?}. Requires alert signal manage. Capped at 50 signals per partner (403 limit_reached); a duplicate name is 409 name_taken.

curl -X POST https://api.blunotify.com/v1/alert-signals \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Freezer, loud warning",
       "entries":{
         "CLEAR":   {"light":{"type":"Solid","color":{"r":0,"g":255,"b":0}}},
         "ADVISORY":{"light":{"type":"Solid","color":{"r":255,"g":255,"b":0}}},
         "WARNING": {"light":{"type":"PulseThenSolid","pulse_time_s":10,
                     "pulse_color":{"r":255,"g":0,"b":0},"pulse_period_s":0.5,
                     "solid_color":{"r":255,"g":0,"b":0},"repeat_s":600}},
         "NO_DATA": {"light":{"type":"Pulse","color":{"r":0,"g":0,"b":255},"period_s":2}}}}'

201 Location: /v1/alert-signals/12
{"id":12}

Update one of your own signals: any of name, description, entries. Global signals (the default among them) and other owners' return 404. Returns the new version. Requires alert signal manage.

Delete one of your own signals. Allowed while lights show it: they go back to the default signal. Requires alert signal manage.

Choose a light's signal. Body: {"alert_signal_id"} — a global signal or one of your own; null (or the default's id) means the default. Any other id is 404. Requires config write.

System API — device MQTT interface

The System API is the partner-facing equivalent of BluNotify's admin Device Console: it reaches a device's system interface (Device API Reference Rev 1.2) — NVS settings, diagnostics, lifecycle (reboot/reset/format), platform-file distribution, and OTA firmware. It is gated by its own independent permission flags and, like everything else, fully audited. Everything here is additive under /v1; nothing about the notification endpoints above changes.

Tiers & confirmation

• System read — served from BluNotify's records (no device traffic): cached settings, status/health, the response feed, the file list, and the command registry.
• System control — structured verbs that publish to the device, plus writes to ordinary NVS keys.
• System destructive — clear settings, factory reset, filesystem format, OTA, and writes to the connection/identity keys below. Every destructive call must include "confirm": "<device-id>" in the body; a missing or mismatched value returns 409 confirmation_required and nothing is sent.

Secret settings values are encrypted for the device

Cellular devices reach the broker in plaintext MQTT over a private carrier VPN, so a settings value that is a credential is never published in the clear. Write a key whose name contains pass, pwd, key, token, secret or psk — in practice wifiPwd, mqttPass, gprsPass — and BluNotify wraps your value in an authenticated envelope only that one device can open, on every transport:

PUT /v1/devices/{id}/system/settings/wifiPwd   {"value": "hunter2"}

202 {"key":"wifiPwd",
     "payload":"wifiPwd=enc1:0mjvF7D3K/Spejqa+tGghX2/Kg3oukqsS5nqCQgWtsuKnO8=", …}

You send the plaintext; the payload you get back is the ciphertext, and so is the device's acknowledgement on the response feed — match acks against the returned payload, never against the value you sent. Nothing else changes: same topic, same QoS, same >ok/>failed suffixes, and the setting still applies on the device's next reboot. Ordinary keys stay cleartext so the traffic remains readable. The raw MQTT channel is treated identically — publishing wifiPwd=… to a device's sys/exe by hand is encrypted the same way.

One limitation worth stating plainly: an envelope is bound to its key name and its device, and cannot be altered — but it is not replay-proof. Anyone who captured an earlier envelope for the same key on the same device could replay it to restore that earlier value. They cannot choose the value, and cannot aim it at a different key or device.

Fire-and-forget & the response feed

Devices are asynchronous: a command is a one-shot publish, not a request/response. So command, settings-write, and raw-publish endpoints return 202 Accepted with the exact topic, payload, and sent_at that were sent. Poll GET /v1/devices/{id}/system/responses and match the acknowledgement: the device replies with your payload followed by >ok, >failed, >applied, or >unknown (e.g. you sent query>, the ack is query>ok). Rows come oldest first. Pass each answer's next_cursor back as cursor for the rows after the last one you have; has_more says whether more are waiting now, and next_cursor is always set, so a poll loop just keeps the latest one. Without a cursor you get the last ten minutes, or the rows at or after since (ISO 8601).

Endpoints

The command registry: every verb, its tier, its parameters, whether it needs confirm, and whether your account currently holds that tier. Also lists the destructive settings keys. Requires system read.

Cached NVS settings (from the device's last connect/query), plus fw_ver and the device file_list. Values the firmware masks appear as *****. Requires system read.

The connectivity fields, last connection string, on-demand status snapshots, and the periodic health heartbeat. Requires system read.

Recent command acknowledgements and device log lines, oldest first. Query params: cursor (a previous answer's next_cursor), limit (default 200, max 1000), and the older since. The answer carries rows, has_more, next_cursor and server_now. Requires system read.

The platform files devices download (files/ + firmware/), each with size and modified time. Requires system read.

Run a structured verb. Body: {"command", "params"?, "confirm"?}. Control verbs need system control; destructive verbs need system destructive + confirm. Returns 202.

curl -X POST https://api.blunotify.com/v1/devices/DEV123/system/commands \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"command":"query"}'

202 {"command":"query","topic":"blunotify/DEV123/sys/exe","payload":"query>","sent_at":"2026-07-07T12:00:00+00:00"}

# destructive verbs require confirm == device id
curl -X POST https://api.blunotify.com/v1/devices/DEV123/system/commands \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"command":"factory_reset","confirm":"DEV123"}'

File-backed verbs reference a file already on the platform file server: addfile / setcert take a name in files/ (the SHA-256 is computed for you); ota_update takes a .bin in firmware/. rmfile removes a file on the device. Call GET /v1/system/commands for the full parameter list. Factory reset erases the MQTT credentials — the device must be re-provisioned (pairs with the device-provisioning permission) before it reconnects. OTA is inert unless the image carries a valid RSA-3072 signature. Uploaded files mirror to storage within ~1 minute before a device can fetch them.

Write one NVS key. Body: {"value", "confirm"?}. Ordinary keys need system control; the connection/identity keys above need system destructive + confirm. Returns 202.

Upload a platform file (multipart: file + dir=files|firmware). Requires file upload. Extension allowlist; firmware/ accepts .bin only; at most 32 MB (larger is 413). Uploads never overwrite — a name clash is 409. Returns 201 with the stored name, size, and SHA-256.

An .mp3 uploaded into files/ is checked against what a BluNotify device can play. One that holds no MP3 (MPEG Layer III) audio — a WAV with an .mp3 name, an MP2 file — is refused with 400 validation_error and the reason. Any other comes back with an audio object: playable, ideal, a one-line summary.text, and issues[] of {code, severity, message} saying what would make it better. Warnings never block the upload. Devices play best from a mono MP3 at 16 kHz and 48 kbps constant bitrate, with no ID3 tags or cover art, mastered loud (peaks around −1.5 dB — a device's volume setting can only turn a file down). All of a device's sound files share about 9.75 MB of storage.

Delete a platform file: ?dir=&name=. Requires file delete. Protected names are refused.

Pushing a file to a device — the durable transfer job

Sending a file with the addfile verb above is fire-and-forget, so you would have to infer arrival by re-reading the device's file list. These endpoints do it properly: the push returns a transfer — a durable job with a correlation token — and you poll that one object until it settles. Nothing else needs to be watched, and no command has to be re-sent to find out what happened.

Body: {"name", "dest"?}. name is a file already in the platform files/ directory (no bytes travel through this call — upload first with POST /v1/system/files); dest is the device-side name and defaults to name. The SHA-256 is always computed server-side and always sent — there is no option to omit it, because the firmware requires it. Requires system control; polling requires system read.

Send an optional Idempotency-Key header to make retries safe (see Retrying safely): a repeat within 24 hours gets the first 202 again, and after that this route still recognises the key, answering 200 with the original transfer as it stands; nothing is downloaded a second time. A new push is 202, with the transfer to poll in its Location header. The response body is the transfer document below, plus device_online on this call only.

curl -X POST https://api.blunotify.com/v1/devices/DEV123/files \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: boot-mp3-attempt-1" \
  -d '{"name":"boot.mp3","dest":"boot.mp3"}'

The same document, resolved as of the read. This is the one thing to poll.

Your transfers for a device, newest first: ?state=&since=&limit=. The reconciliation read for a client that was down while transfers were in flight.

The transfer document

{
  "transfer_id": "ft_48abbe9daf9e0e9bae04500654c97c7a",
  "device_id":   "DEV123",
  "state":       "sent",          // queued | sent | succeeded | failed | timed_out
  "terminal":    false,           // poll until this is true
  "src":         "boot.mp3",
  "dest":        "boot.mp3",
  "sha256":      "64d0f6…",
  "corr_mode":   "envelope",      // or "url_token" — informational only
  "attempts":    1,
  "detail":      null,            // the device's reply / failure reason once terminal
  "poll_after_s": 15.0,           // seconds to wait before the next poll; null once terminal
  "note":        "…",             // present while "sent" — explains the offline window
  "timeline": { "created_at": "…", "sent_at": "…",
                "ack_deadline": "…", "settled_at": null }
}

Raw MQTT channel

Two scope levels: Raw MQTT — in-scope devices only permits topics/filters under blunotify/{in-scope-id}/… only; Raw MQTT — ANY topic permits any syntactically valid topic.

Publish an arbitrary payload. Body: {"topic", "payload", "retain"?, "qos"?} (retain default false; qos default 2 for sys/*, else 1; publish topics may not contain wildcards). Returns 202. A raw publish is sent as written: it is not checked against the settings catalog, so none of the settings route's range checks or refusals apply to it.

Read recorded broker traffic by MQTT topic filter (+/# wildcards): ?topic=&limit=. The first call returns the newest rows, newest first; pass its next_cursor back as cursor to follow what arrives after them, oldest first, with has_more as on the response feed. The older since still filters the first call. Under the in-scope-devices-only scope the filter must sit under one in-scope device's subtree (a device-spanning filter like blunotify/+/… is rejected). History depth is bounded by BluNotify's message-retention window.

BluEM API — energy monitor devices

BluEM is a second product on the platform: a single-phase energy monitor (a PZEM-004T power meter behind an ESP32). Its product routes live under their own prefix, /v1/bluem, rather than the paths above. The product-agnostic parts of /v1/devices/… — the device list and GET /v1/devices/{id}, GET …/state, GET …/health, the System API and file transfers — serve an in-scope BluEM device exactly as they serve a BluNotify one (the device list says which is which: "product":"bluem", and GET /v1/devices?product=bluem lists meters only); only BluNotify's product routes (raw commands, effects, automation, sensors) refuse it, and a BluNotify device is likewise refused everywhere under /v1/bluem/… — in both cases with the same 404 an out-of-scope device gets, so neither product surface reveals a foreign device's product by answering differently. Everything above this section (auth, rate limits, error shape, the System API's fire-and-forget/response-feed conventions) applies here unchanged.

What a meter reports

A BluEM device does not stream values; it keeps interval records — average/min/max per quantity (volts, amps, watts, hertz, power factor) over a reporting period (15 minutes by default), plus its lifetime energy counter — and resends each until the server has stored it. GET …/intervals reads that history record by record; GET …/summary adds up a window of it for you; GET …/energy reads the same table pre-bucketed into hourly or daily consumption. For what the meter reads right now, ask for a live reading.

Integrator notes

Read these before you write your sync. Each one is something the data does that a first integration usually gets wrong.

Requires energy data read. Query params: start/end (ISO-8601 or epoch seconds; end defaults to now, start to 24h before it, and the span is capped at a year), limit (default 200, max 1000), cursor (a previous page's next_cursor, verbatim), and unknown_time. A record is in the window when its midpoint is.

{"device_id":"EM123","unknown_time":false,
 "window":{"start":"2026-09-24T12:00:00+00:00","end":"2026-09-25T12:00:00+00:00"},
 "records":[
   {"seq":118,"sid":"1a2b3c4d","start_at":"2026-09-25T11:45:00+00:00",
    "time_quality":"device","duration_s":900,
    "reads":{"n":900,"err":0},
    "voltage_v":{"avg":229.83,"min":228.1,"max":231.4},
    "current_a":{"avg":1.203,"min":0.9,"max":1.6},
    "power_w":{"avg":276.1,"min":205.0,"max":370.0},
    "frequency_hz":{"avg":50.01,"min":49.9,"max":50.1},
    "power_factor":{"avg":0.947,"min":0.9,"max":0.99},
    "energy_wh":{"first":100020.0,"last":100089.0},
    "ct_turns":1,
    "alarm_reads":0,
    "flags":{"partial":false,"energy_reset":false,"meter_reconfigured":false},
    "quarantined":false,"quarantine_reason":null,
    "received_at":"2026-09-25T12:00:01.532+00:00"}],
 "has_more":false,
 "next_cursor":null}

received_at is when the server took the record off the network. For a record sent on time it is a second or two after the interval ended; for one a meter stored through an outage it is much later than start_at.

Records come back oldest first, ordered by (start, stream id, sequence number) and paginated by that same key — pass a page's next_cursor straight back as cursor for the next one. has_more is true exactly when there is a next page; on the last page it is false and next_cursor is null. A cursor contains only letters, digits, - and _, so it goes into a URL as it is. An unparseable cursor is a 400, never a silent restart from the first page.

A cursor remembers its window. The next page is cut from the start and end the first page used, even if you left them out and the default "last 24 hours" has moved on since. Beside a cursor you may leave start, end and unknown_time out; if you send them, they must be the values the first page was asked with (the same instant, in any format), or the call is a 400 validation_error.

Names and units. Every measurement is named for its quantity and its unit, in the base unit: voltage_v (volts), current_a (amperes), power_w (real, or active, power in watts), frequency_hz (hertz) and power_factor (no unit). Energy is in watt-hours everywhere (energy_wh), times end in _at, and durations are in seconds. The same names are used on every BluEM route.

Every measurement is rounded to 6 decimal places — past the finest stored resolution — and is null, not zero, when the record carries no reading for that quantity: a quarantined record, or one where the meter went unanswered (reads.n = 0). current_a, power_w and energy_wh are corrected for CT turns: the meter reads ct_turns × the real current when the load conductor is wrapped through its current transformer more than once (emCtTurns), and the server divides those three by the record's own ct_turns before storing it — so energy_wh is a number, not an integer, and ct_turns is carried on every record (1 for firmware that never sent it; null on a quarantined record whose value was unusable, whose current_a, power_w and energy_wh are then null too). voltage_v, frequency_hz and power_factor are as measured. A change of emCtTurns closes the interval in progress (flagged partial), so no record mixes two values. A record whose start time could not be determined (the device rebooted before it ever learned the time) has "start_at": null and is never included unless you pass unknown_time=true, in which case only such records come back, ordered by sequence number and filtered by when they arrived rather than by start/end (they have no start to filter by).

Requires energy data read. A window's statistics, added up by the server so you do not have to page through …/intervals. Query params: start/end, exactly as …/intervals takes them (the last 24 hours by default, at most a year).

curl "https://api.blunotify.com/v1/bluem/devices/EM123/summary?start=2026-09-29T14:00:00Z&end=2026-09-30T14:00:00Z" \
  -H "Authorization: Bearer $KEY"

200 {"device_id":"EM123",
     "window":{"start":"2026-09-29T14:00:00+00:00","end":"2026-09-30T14:00:00+00:00"},
     "coverage":{"records":96,"quarantined":0,"seconds":86391},
     "voltage_v":   {"avg":123.077838,"min":119.6,"max":125.3, "intervals":96,"seconds":86391},
     "current_a":   {"avg":0.336163,  "min":0.0,  "max":6.9894,"intervals":96,"seconds":86391},
     "power_w":     {"avg":31.99751,  "min":0.0,  "max":764.92,"intervals":96,"seconds":86391},
     "frequency_hz":{"avg":59.967292, "min":59.9, "max":60.0,  "intervals":96,"seconds":86391},
     "power_factor":{"avg":0.693137,  "min":0.0,  "max":0.96,  "intervals":55,"seconds":49493},
     "energy_wh":{"total":769.0,"resets":0,"intervals":96}}

There is no duty cycle or other analysis in the summary: that is yours to compute from …/intervals.

Pulling only what is new: the arrival feed

Requires energy data read. The same route, asked a different way: instead of a window of start times, you ask for everything the server has stored since a point you keep. The server gives you a bookmark with every answer. Follow the bookmark and you receive every record exactly as it is stored, late ones included, and never miss one.

1. First call. Pass received_since: the time to start from (ISO-8601 or epoch seconds). You get the records the server received at or after it.
2. Keep the bookmark. Every answer carries next_cursor. It is never null in this mode, even when there are no records. Save it.
3. Every later call. Pass cursor=<the saved bookmark> and nothing else (limit is allowed). While has_more is true, call again at once with the new bookmark. When it is false you have everything; call again whenever you next want to check.

curl "https://api.blunotify.com/v1/bluem/devices/EM123/intervals?received_since=2026-09-27T00:00:00Z" \
  -H "Authorization: Bearer $KEY"

200 {"device_id":"EM123","mode":"received",
     "received_since":"2026-09-27T00:00:00+00:00",
     "records":[ …record documents, as above… ],
     "has_more":false,
     "next_cursor":"cnw4MDgxNzMwMXwxYTJiM2M0ZHwxMTh8MTc5MDU3MDAwMA"}

curl "https://api.blunotify.com/v1/bluem/devices/EM123/intervals?cursor=cnw4MDgxNzMwMXwxYTJiM2M0ZHwxMTh8MTc5MDU3MDAwMA" \
  -H "Authorization: Bearer $KEY"

200 {"device_id":"EM123","mode":"received","received_since":null,
     "records":[],"has_more":false,
     "next_cursor":"cnw4MDgxNzMwMXwxYTJiM2M0ZHwxMTh8MTc5MDU3MDAwMA"}

BluEM settings. A meter's settings are written with the same PUT /v1/devices/{id}/system/settings/{key} as any device (system control). On a BluEM device the meter keys — emReportSec, emSampleMs, emAlign, emAckTmoSec, emBatchMax, emMaxBytes — are checked against the product's settings catalog before anything is sent, so an out-of-range value is a 400 validation_error rather than a value the meter quietly clamps; the retired emLiveSec and pmPollSec are refused the same way. These keys take effect on the meter within seconds, with no reboot. For a report every five minutes: PUT /v1/devices/EM123/system/settings/emReportSec {"value": "300"} (10–86400; a shorter interval uses more cellular data).

Four keys cannot be written through this route: emAck, pmBaud, pmSlave and emCtTurns. They are fixed by the meter hardware and by how the unit is wired, and a wrong value fails silently: emAck=0 removes the delivery guarantee, a wrong pmBaud or pmSlave stops every reading, and a wrong emCtTurns rescales every reading. The answer is 403 forbidden with the reason, whatever your permissions, and nothing is sent. Every record still reports the ct_turns it was measured under.

Requires energy data read. Query params: bucket — hour or day, default hour — and start/end as above. The buckets you get are always exactly the width you asked for, never silently coarser: a window the bucket cannot cover in under 2000 buckets is a 400 validation_error, so an hour-bucketed range must span fewer than 2000 hours (83 days) — ask for bucket=day beyond that.

Your own days and hours: tz. Without it, a day is a UTC day and an hour a UTC hour, exactly as before. Pass tz with an IANA zone name (tz=America/New_York) and the buckets are that zone's local days or hours, so a daily total matches what the Energy Monitoring page shows a reader in that zone. Nothing is stored: send it on every request that should use it.

curl "https://api.blunotify.com/v1/bluem/devices/EM123/energy?bucket=day&tz=America/New_York&start=2026-10-31T04:00:00Z&end=2026-11-02T05:00:00Z" \
  -H "Authorization: Bearer $KEY"

200 {"device_id":"EM123","bucket":"day","tz":"America/New_York",
     "window":{"start":"2026-10-31T04:00:00+00:00","end":"2026-11-02T05:00:00+00:00"},
     "points":[{"start_at":"2026-10-31T00:00:00-04:00","energy_wh":6624.0,"reset":false},
               {"start_at":"2026-11-01T00:00:00-04:00","energy_wh":6911.0,"reset":false}],
     "total":{"energy_wh":13535.0,"resets":0,"intervals":196,"buckets":2}}

{"device_id":"EM123","bucket":"day",
 "window":{"start":"…","end":"…"},
 "points":[{"start_at":"2026-09-25T00:00:00+00:00","energy_wh":6624.0,"reset":false}],
 "total":{"energy_wh":6624.0,"resets":0,"intervals":96,"buckets":1}}

total is null — not zero — when no record in the window carried a counter reading at all (a brand-new meter, or one silent the whole window): "no readings" and "used nothing" are different facts. A bucket's reset is true if the meter's lifetime counter was zeroed during it (by cmd/resetenergy below, or a factory reset); that bucket's own consumption is counted from zero rather than showing a false negative. Consumption is in watt-hours (Wh), corrected for CT turns like a record's energy_wh, and a change of emCtTurns is never reported as a reset: the interval after the change counts its own first-to-last reading, because the meter's lifetime counter does not restart when the turns change.

Requires system control. Asks the meter to close the interval in progress right now and send it, instead of waiting for its reporting period to elapse. Fire-and-forget — 202 with the topic/payload/sent_at, same shape as a System API command — and the record it produces carries a partial flag and reaches GET …/intervals a few seconds later; nothing is lost.

Live reading

What the meter reads right now: volts, amps, watts, power factor and frequency. It closes no interval and stores no record, so it is safe to use when a reading is wanted, for example to check an installation. The server never waits for the meter: you ask, you get a token, and you check back with the token. An answer normally takes one to three seconds on cellular.

Requires energy data read. No body.

curl -X POST https://api.blunotify.com/v1/bluem/devices/EM123/sample \
  -H "Authorization: Bearer $KEY"

202 {"device_id":"EM123","token":"5f3a9c1e","state":"pending",
     "requested_at":"2026-09-28T14:02:11.482+00:00","timeout_s":30}

Requires energy data read. Ask every second or two until state is no longer pending. It is final within 30 seconds. The 202 from POST …/sample names this URL in its Location header.

curl https://api.blunotify.com/v1/bluem/devices/EM123/sample/5f3a9c1e \
  -H "Authorization: Bearer $KEY"

200 {"device_id":"EM123","token":"5f3a9c1e","state":"done","reason":null,
     "requested_at":"2026-09-28T14:02:11.482+00:00",
     "reading":{"link":"ok","answered":true,
                "voltage_v":122.0,"current_a":0.6268,"power_w":58.54,
                "power_factor":0.77,"frequency_hz":60.0,
                "ct_turns":5,"age_s":0,
                "taken_at":"2026-09-28T14:02:12.760+00:00","took_s":1.278}}

A quantity the meter has no value for is null, never zero: a meter with no voltage on its leads does not answer, and that is not the same as a load drawing nothing. A token that was not issued for this meter is 404, exactly like an unknown meter. The reading is not stored as an interval record and does not appear in GET …/intervals.

Requires energy reset — a flag of its own, off by default and independent of every other BluEM/System flag — plus a body {"confirm": "<device-id>"} matching the device id exactly, the same as a destructive System API verb. A missing or mismatched confirm is 409 confirmation_required and nothing is sent.

curl -X POST https://api.blunotify.com/v1/bluem/devices/EM123/resetenergy \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"confirm":"EM123"}'

202 {"topic":"bluem/EM123/cmd/resetenergy","payload":"5b1e…-token",
     "sent_at":"…","token":"5b1e…-token"}

Requires energy reset (the same flag as the request). Poll with the token from the 202 above for the outcome; that 202 names this URL in its Location header:

A token never issued for this device is 404, exactly like an unknown or out-of-scope device — it cannot be used to read another meter's log.

Demo access

Before production access, BluNotify staff provision a demo partner and a demo light, and issue you a key. A typical first session:

1. GET /v1/account — confirm your permissions.
2. GET /v1/devices — find your demo device id and channels.
3. GET /v1/commands — see the commands and parameter ranges granted to you.
4. POST /v1/devices/{id}/channels/light2/effects with {"command":"flash_white"} — trigger a visible overlay.

Contact your BluNotify representative to arrange demo credentials.

Extending predefined commands

New named commands are added by BluNotify developers at management's request (they are implemented in code, reviewed, and tested, then granted to your account). If you need a specific effect, describe the behavior to your representative and it can be added as a new command without changing your integration — it simply appears in GET /v1/commands once granted.

Versioning and deprecation

/v1 only gains things. After launch, /v1 changes only by adding: new routes, new optional parameters, new response fields, new error codes. Anything that would break a working client goes into a new version (/v2), and /v1 keeps working beside it. Every cursor and bookmark already issued keeps working too.

What counts as breaking:

• removing or renaming a route, a parameter, a response field or an enum value;
• changing a field's type, unit or meaning, or the status code or code of an error;
• making an optional parameter required, changing a default, or refusing input that was accepted;
• a cursor or bookmark that was issued no longer working.

Your client must ignore what it does not know. Additions are only safe if clients allow for them: ignore response fields you do not recognise, handle an error code you do not know by its HTTP status, and do not fail on an enum value you have not seen.

Deprecation. Something that is to be removed is deprecated first, and keeps working for at least six months before its sunset date. When it is announced:

• BluNotify staff email your account's contact address;
• it is listed, with its dates, in the changelog;
• every response that uses it carries Deprecation (RFC 9745: since when), Sunset (RFC 8594: the date it stops working) and Link: </changelog#…>; rel="deprecation" headers;
• /openapi.json and the reference mark it deprecated.

Watch for the Deprecation header in your logs: it is the earliest signal a call you rely on is going away.