NotifyBridge – API Docs

Authentication

Every request needs a user_key to identify your account and an api_token to authenticate your app. Both are passed in the JSON request body — there are no authentication headers.

Field	Description
user_key	Your account identifier. Treat it like a password — keep it private.
api_token	Per-app token (UUID). Generated when you create an app in the NotifyBridge app.

Call this API from a server or device, not from a browser. Credentials travel in the request body, and the API does not send CORS headers — a fetch() from a web page will fail its preflight check.

Send a Notification (broadcast)

POST/v1/messages/send

With no device specified, the notification is delivered to every device claimed under this app — plus your own registered devices. Handy while testing; to target one unit, see Send to a Device below.

Request body

Field		Description
api_token	required	Your app's API token
user_key	required	Your account user key
message	required	Notification body text
device_name	optional	Narrow the broadcast to subscriber devices with this name. Useful for multi-device households.
priority	optional	Integer from -1 to 2. Default: 0. See priority table below.

Examples

curl -X POST https://notifybridge.mindeon.net/v1/messages/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_token": "YOUR_API_TOKEN",
    "user_key": "YOUR_USER_KEY",
    "message": "Deploy finished successfully",
    "priority": 1
  }'

import requests

requests.post(
    "https://notifybridge.mindeon.net/v1/messages/send",
    json={
        "api_token": "YOUR_API_TOKEN",
        "user_key": "YOUR_USER_KEY",
        "message": "Deploy finished successfully",
        "priority": 1,
    },
)

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "api_token": "YOUR_API_TOKEN",
        "user_key":  "YOUR_USER_KEY",
        "message":   "Deploy finished successfully",
        "priority":  1,
    })
    http.Post(
        "https://notifybridge.mindeon.net/v1/messages/send",
        "application/json",
        bytes.NewReader(body),
    )
}

require "net/http"
require "json"

uri = URI("https://notifybridge.mindeon.net/v1/messages/send")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req.body = {
  api_token: "YOUR_API_TOKEN",
  user_key:  "YOUR_USER_KEY",
  message:   "Deploy finished successfully",
  priority:  1
}.to_json

http.request(req)

await fetch("https://notifybridge.mindeon.net/v1/messages/send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_token: "YOUR_API_TOKEN",
    user_key:  "YOUR_USER_KEY",
    message:   "Deploy finished successfully",
    priority:  1,
  }),
});

$ch = curl_init("https://notifybridge.mindeon.net/v1/messages/send");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode([
        "api_token" => "YOUR_API_TOKEN",
        "user_key"  => "YOUR_USER_KEY",
        "message"   => "Deploy finished successfully",
        "priority"  => 1,
    ]),
]);
curl_exec($ch);

Response

{ "success": true, "sent": 2 }

Send to a Device

POST/v1/messages/send

Same endpoint, with a device identified. The notification goes only to the subscriber who claimed that device — this is what shipped firmware should send. The device must be claimed first.

Request body

Field		Description
api_token	required	Your app's API token
user_key	required	Your account user key
message	required	Notification body text
device_code	one of these	The device's MS-XXXX-XXXX device code.
relay_id	one of these	Alternative to device_code. The internal device ID (e.g. relay_abc123).
device_name	optional	Target a specific subscriber device by name. Useful for multi-device households.
priority	optional	Integer from -1 to 2. Default: 0.

Supply device_code or relay_id, not both. Omitting both is valid but broadcasts — see the section above.

Examples

curl -X POST https://notifybridge.mindeon.net/v1/messages/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_token": "YOUR_API_TOKEN",
    "user_key": "YOUR_USER_KEY",
    "device_code": "MS-ABCD-EF12",
    "message": "Door sensor triggered"
  }'

import requests

requests.post(
    "https://notifybridge.mindeon.net/v1/messages/send",
    json={
        "api_token":  "YOUR_API_TOKEN",
        "user_key":   "YOUR_USER_KEY",
        "device_code": "MS-ABCD-EF12",
        "message":    "Door sensor triggered",
    },
)

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "api_token":  "YOUR_API_TOKEN",
        "user_key":   "YOUR_USER_KEY",
        "device_code": "MS-ABCD-EF12",
        "message":    "Door sensor triggered",
    })
    http.Post(
        "https://notifybridge.mindeon.net/v1/messages/send",
        "application/json",
        bytes.NewReader(body),
    )
}

require "net/http"
require "json"

uri = URI("https://notifybridge.mindeon.net/v1/messages/send")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req.body = {
  api_token:  "YOUR_API_TOKEN",
  user_key:   "YOUR_USER_KEY",
  device_code: "MS-ABCD-EF12",
  message:    "Door sensor triggered"
}.to_json

http.request(req)

await fetch("https://notifybridge.mindeon.net/v1/messages/send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_token:  "YOUR_API_TOKEN",
    user_key:   "YOUR_USER_KEY",
    device_code: "MS-ABCD-EF12",
    message:    "Door sensor triggered",
  }),
});

$ch = curl_init("https://notifybridge.mindeon.net/v1/messages/send");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode([
        "api_token"  => "YOUR_API_TOKEN",
        "user_key"   => "YOUR_USER_KEY",
        "device_code" => "MS-ABCD-EF12",
        "message"    => "Door sensor triggered",
    ]),
]);
curl_exec($ch);

Response

{ "success": true, "sent": 1 }

Errors

400 Missing fields — api_token, user_key, and message are all required
401 Invalid api_token or user_key
403 Device does not belong to this user
403 Device is not claimed
403 api_token does not match the device's app
404 Device not found — no device matches that device_code or relay_id
404 No devices found — the device is claimed, but no subscriber device is registered and enabled
429 Monthly push limit reached

Looking for a specific board? The NotifyBridge-Devices repository has ready-to-flash examples for ESP32, Arduino, Raspberry Pi, and more.

Notification Priorities

Value	Name	Sound	Interruption	Use case
2	Emergency	Critical (overrides silent)	critical	Life-critical alerts
1	High	Default	time-sensitive	Important alerts, cuts through Focus
0	Normal	Default	active	Standard notifications
-1	Low	None	passive	Background info, no interruption

Monthly Allocation

Every account includes 3,000 pushes per month across all apps, resetting at the start of each calendar month. Need more? Additional push credits can be purchased inside the app and never expire — they carry over until consumed.

Once your allocation is exhausted, the API returns 429 until credits are added or the month resets:

{ "success": false, "error": "Monthly push limit reached", "limit": 3000 }

limit is your effective ceiling — 3,000 plus any purchased credits — so it reads higher than 3000 once you have credits on the account. The free monthly allowance is consumed first; credits raise the ceiling above it. Usage resets at the start of each calendar month, UTC.

Error Responses

All errors follow the same format:

{ "success": false, "error": "descriptive message" }

Status	Meaning
400	Missing or invalid fields in the request
401	Invalid api_token or user_key
403	Permission denied
404	Resource not found
429	Monthly allocation exhausted — add credits or wait for reset
500	Internal server error