BluNotify Partner API

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 of the complete API is available at /openapi.json, and the reference lists every route, parameter and field from it. For BluEM energy monitors, start with the BluEM quick start. Changes after launch are listed in the changelog.

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

Your account is granted specific permission flags; confirm yours at GET /v1/account. This guide covers two of them:

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 your key lacks a flag the request needs, the 403 names it as required_permission, by its GET /v1/account key (shown under each flag above).

Devices & channels

You can only see and control devices in your scope — devices inside an organization subtree granted to your account, plus any device at all if your account has the access-all-devices scope flag (see the full API reference for how scope is granted). Your account is scoped to these channels:

Your allowed channels are configured per partner, across your whole scope. GET /v1/devices lists your devices and their permitted channels.

Endpoints

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

Devices in your scope. Each: device_id, name, product (blunotify for a notification light) and channels. ?product=blunotify lists only those.

A single device in your scope.

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

Trigger a predefined command with optional parameters, on light2, light3, or sound. Requires the predefined-commands 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"}

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 response never includes the underlying encoded command string for this permission level — just 202 Accepted, confirming that it was sent.

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

{"device_id":"DEV123","state":{"light2":{"label":"White (Flashing)","updated_at":"2026-07-04T12:00:00+00:00"}}}

Each channel returns a human-readable label and updated_at — not the raw encoded command string.

Command parameters

Parameterized effects accept fields such as period_s, duty_ratio, 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.

Error codes

Errors are JSON: {"error":"…","code":"…","request_id":"…"}. Every response also carries the same id in an X-Request-Id header: quote it when you contact BluNotify support.

Rate limits

Limits apply per partner (requests/minute) and per device (commands/minute), plus a global per-device ceiling shared across partners. Exceeding a limit returns 429 with a Retry-After header (seconds). Build in backoff and avoid tight retry loops. Every response also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds) for your per-partner request limit, so you can slow down before you reach it.

Conflicts

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.