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",
    "senderName": "GitHub",
    "senderIcon": "https://github.githubassets.com/favicons/favicon.png",
    "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
senderName	string	No	—	Custom sender name shown on notification (replaces "notfs")
senderIcon	string	No	—	URL to custom icon (PNG/JPEG). Replaces app icon on notification

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

Custom Sender Name & Icon

Replace the default "notfs" app icon and name on notifications with your own branding. This uses iOS Communication Notifications to display a custom avatar and sender name — your notification looks like it came from any app you want.

curl -X POST https://api.notfs.dev/api/notifications \
  -H "X-API-Key: ntfs_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New PR Review",
    "body": "alice approved your pull request #42",
    "senderName": "GitHub",
    "senderIcon": "https://github.githubassets.com/favicons/favicon.png"
  }'

senderName — Shown as the sender on the notification banner. Max 50 chars.

senderIcon — URL to a PNG or JPEG image. Shown as a circular avatar replacing the app icon. Max 5MB. Square images work best.

If only senderName is provided, the name changes but the icon stays as the notfs logo. If only senderIcon is provided, the icon changes with "notfs" as the sender name.

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"
      }'