Send Notification

Name: notfs
Rating: 4.8 (50 reviews)
Author: notfs

POST /api/notifications

Schedule a push notification to your registered devices. Requires an API key with notifications:write scope.

Request

curl -X POST https://api.notfs.dev/api/notifications \
  -H "X-API-Key: ntfs_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy reminder",
    "body": "Push v2.4.1 to production",
    "iconStyle": "bolt",
    "sound": "default",
    "delay": "5m",
    "priority": "high",
    "metadata": {
      "pr": "847",
      "env": "production"
    }
  }'

Response (201)

{
  "id": "clx...",
  "title": "Deploy reminder",
  "body": "Push v2.4.1 to production",
  "status": "QUEUED",
  "scheduledAt": "2026-02-15T12:05:00.000Z",
  "createdAt": "2026-02-15T12:00:00.000Z",
  "devicesTargeted": 1
}

Parameters

Field	Type	Required	Default	Description
title	string	Yes	—	Notification title (1-200 chars)
body	string	No	""	Notification body (max 2000 chars)
iconStyle	enum	No	"bolt"	bolt, bell, terminal, stack
sound	enum	No	"default"	default, soft, critical
delay	enum	No	"5s"	5s, 30s, 1m, 5m, 15m, 30m, 1h, custom
customDelay	int	No	—	Seconds (1-86400). Required if delay=custom
priority	enum	No	"normal"	low, normal, high, critical
targetDeviceToken	string	No	—	Target a specific device. If omitted, sends to all
metadata	object	No	—	Arbitrary key-value string pairs
scheduledAt	ISO 8601	No	—	Exact schedule time. Overrides delay

Status Flow

SCHEDULED → QUEUED → DELIVERED
                  ↘ FAILED
SCHEDULED → CANCELLED (via DELETE)

SCHEDULED — Created, waiting for device registration or queue

QUEUED — Enqueued for delivery via APNs

DELIVERED — Successfully sent to device

FAILED — APNs rejected the notification

CANCELLED — Cancelled before delivery

Code Examples

Python

import requests

response = requests.post(
    "https://api.notfs.dev/api/notifications",
    headers={"X-API-Key": "ntfs_your_key"},
    json={
        "title": "Build failed",
        "body": "CI #847 failed on main",
        "priority": "critical",
        "delay": "5s",
    },
)
print(response.json())

JavaScript

const res = await fetch("https://api.notfs.dev/api/notifications", {
  method: "POST",
  headers: {
    "X-API-Key": "ntfs_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "New signup",
    body: "user@example.com registered",
    delay: "5s",
  }),
});
const data = await res.json();

GitHub Actions

- name: Notify via notfs
  run: |
    curl -X POST https://api.notfs.dev/api/notifications \
      -H "X-API-Key: ${{ secrets.NOTFS_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Deploy ${{ github.ref_name }}",
        "body": "${{ github.event.head_commit.message }}",
        "priority": "high",
        "delay": "5s"
      }'