API reference

Four endpoints. Your backend touches one of them; the script handles the rest.

Browser API

notify.subscribe(userId)

Asks permission, creates the push subscription, and registers it against userId. Returns the subscription. Safe to call repeatedly.

await notify.subscribe(currentUser.id)

HTTP API

Create a project

Mints a project with a publishable + secret key pair. This is what npx notify-dev init calls. Rate-limited per IP.

{
  "publishableKey": "ntfy_pk_...",   // browser, /subscribe
  "secretKey": "ntfy_sk_..."         // server, /send (keep private)
}

Get the VAPID public key

Returns the public key the browser needs to subscribe. notify.js calls this for you.

{ "vapidPublicKey": "BPx..." }

Register a subscription

Called by notify.js. Authenticates with the publishable key (the token field). Stores the browser subscription against a user id.

{
  "token": "ntfy_pk_...",          // publishable key
  "userId": "user_123",
  "subscription": {
    "endpoint": "https://...",
    "keys": { "p256dh": "...", "auth": "..." }
  }
}

Send a notification

The only endpoint your backend calls. Authenticates with the secret key (the token field) — keep it server-side. Looks up the user’s device and delivers the push. Rate-limited per key and per IP.

{
  "token": "ntfy_sk_...",          // secret key (server-side only)
  "userId": "user_123",
  "title": "Acme",                 // optional, defaults to "notify"
  "body": "Your export is ready!"
}

Status codes

• 200 — delivered / stored
• 400 — malformed body
• 401 — unknown or wrong-type key (e.g. a publishable key on /send)
• 404 — no subscription for that user
• 429 — rate limit exceeded