POST /api/notify

Send a notification to Notifiq.

Request

POST /api/notify
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Body

Field	Type	Required	Description
title	string	Yes	Short summary of the notification
message	string	Yes	Full message body
level	string	No	success, info, warning, error, critical (default: info) or custom level
ttl	integer	No	Display duration on panels in milliseconds
ip	string	No	Sender-supplied IP (e.g. the sending host's internal/private IP). Independent of the auto-detected connection IP shown as "Source IP" in History — useful when Notifiq sits behind a proxy/NAT and the connection IP doesn't reflect the real origin. Usable in History search (ip:) and Routing Rules.
host	string	No	Sender-supplied hostname of the origin system. Usable in History search (host:) and Routing Rules.

Example

{
  "title": "CPU load high on web-01",
  "message": "15-min load average: 8.2 (threshold: 4.0)",
  "level": "critical",
  "ttl": 30000,
  "ip": "10.0.5.22",
  "host": "web-01"
}

Header-based sending

As an alternative to a JSON body, you can pass all fields as HTTP headers. This is useful for tools and monitoring systems that can set custom headers but cannot send a JSON body (e.g. some uptime monitors, simple wget calls).

Header	Description
X-Title	Notification title
X-Message	Message body
X-Level	Level (success, info, warning, error, critical) or custom
X-TTL	TTL in milliseconds
X-IP	Sender-supplied IP
X-Host	Sender-supplied hostname

If both a JSON body field and the corresponding header are provided, the JSON body takes precedence.

Example

curl -X POST https://notify.yourdomain.com/api/notify \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Title: Disk usage critical" \
  -H "X-Message: /dev/sda1 is at 95%" \
  -H "X-Level: critical"

Or with wget (no JSON body needed):

wget -q -O- \
  --header="Authorization: Bearer YOUR_TOKEN" \
  --header="X-Title: Server rebooted" \
  --header="X-Level: warning" \
  --post-data="" \
  https://notify.yourdomain.com/api/notify

Response

Success — 200 OK

{ "ok": true }

Error — 400 Bad Request

{ "error": "title is required" }

Error — 401 Unauthorized

{ "error": "unauthorized" }

Error — 403 Forbidden

Token lacks the notify scope.

{ "error": "forbidden" }

Error — 429 Too Many Requests

Rate limit exceeded.

Examples

curl

curl -X POST https://notify.yourdomain.com/api/notify \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Disk usage critical on storage-01",
    "message": "Device /dev/sda1 is at 95% capacity",
    "level": "critical"
  }'

Python

import requests

requests.post(
    "https://notify.yourdomain.com/api/notify",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "title": "Backup failed",
        "message": "Backup job timed out after 3600s",
        "level": "error",
    }
)

Node.js

await fetch("https://notify.yourdomain.com/api/notify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Deployment complete",
    level: "success"
  }),
})

Bash / monitoring scripts

#!/bin/bash
NOTIFIQ_URL="https://notify.yourdomain.com"
NOTIFIQ_TOKEN="YOUR_TOKEN"

notifiq_send() {
  curl -sf -X POST "$NOTIFIQ_URL/api/notify" \
    -H "Authorization: Bearer $NOTIFIQ_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"title\": \"$1\", \"level\": \"${2:-info}\", \"message\": \"${3:-script}\"}"
}

notifiq_send "Server rebooted" "warning" "Server has been rebooted"