Sending Notifications

Requirements

An API key with notify or full scope
The App ID of the app to send notifications to

Send to All Subscribers

Send a notification to all active subscribers of the app.

curl -X POST https://api.todoke.dev/api/v1/notify \
  -H "Authorization: Bearer pk_notify_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Update",
    "body": "There is an update available",
    "url": "https://yourapp.com/news",
    "icon": "https://yourapp.com/icon.png"
  }'

import { PushCF } from "@elchika-inc/todoke";

const client = new PushCF({
  apiKey: "pk_notify_key",
});

await client.notify({
  title: "New Update",
  body: "There is an update available",
  url: "https://yourapp.com/news",
  icon: "https://yourapp.com/icon.png",
});

await fetch("https://api.todoke.dev/api/v1/notify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pk_notify_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "New Update",
    body: "There is an update available",
    url: "https://yourapp.com/news",
  }),
});

Send to a Specific User

Specify the endpoint field to send to only that subscriber.

curl -X POST https://api.todoke.dev/api/v1/notify \
  -H "Authorization: Bearer pk_notify_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Message for you",
    "body": "This is a targeted notification",
    "endpoint": "https://fcm.googleapis.com/fcm/send/..."
  }'

Batch Send

Send to multiple endpoints in a single request using the batch API.

curl -X POST https://api.todoke.dev/api/v1/notify/batch \
  -H "Authorization: Bearer pk_notify_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoints": [
      "https://fcm.googleapis.com/fcm/send/endpoint1",
      "https://fcm.googleapis.com/fcm/send/endpoint2"
    ],
    "payload": {
      "title": "Batch notification",
      "body": "Sent to multiple users"
    }
  }'

Response: { "queued": 2 }

Check the Recipient Count with a Dry Run

Set dry_run: true to run the same input, URL, payload-size, plan-limit, and rate-limit validation as a real send without enqueueing anything. A dry run does not update notification_logs or monthly_usage.

curl -X POST https://api.todoke.dev/api/v1/notify \
  -H "Authorization: Bearer pk_notify_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Update",
    "body": "There is an update available",
    "dry_run": true
  }'
# → 200 { "ok": true, "dry_run": true, "queued": 0, "would_send": 42 }

For POST /api/v1/notify, omitting endpoint returns the app’s active subscriber count. When endpoint is set, the count is 1 only if it is an active subscription for the same app; otherwise it is 0. For POST /api/v1/notify/batch, set dry_run: true at the top level of the body; matching active subscriptions are counted without duplicates. A successful dry-run response does not include send_id.

Request Parameters

`POST /api/v1/notify`

Field	Type	Required	Description
`title`	string	✅	Notification title
`body`	string	✅	Notification body
`url`	string	—	URL to navigate to on click
`icon`	string	—	Notification icon URL
`badge`	string	—	Badge icon URL
`endpoint`	string	—	If specified, sends only to this subscriber
`dry_run`	boolean	—	When `true`, only validate and return the expected recipient count

`POST /api/v1/notify/batch`

Field	Type	Required	Description
`endpoints`	string[]	✅	List of endpoints (max 100 items; returns 400 `TOO_MANY_ENDPOINTS` if exceeded)
`payload.title`	string	✅	Notification title
`payload.body`	string	✅	Notification body
`payload.url`	string	—	URL to navigate to on click (`https://` only)
`dry_run`	boolean	—	When `true`, only validate and return the expected recipient count

title and body are required. url / icon / badge only allow https:// URLs; specifying an http:// URL returns 400 INVALID_URL.

Limits and Errors

Payload size: the combined size of title / body / url / icon / badge is limited to 3,072 bytes (returns 413 PAYLOAD_TOO_LARGE if exceeded)
Monthly sends: the Free plan is limited to 30,000 notifications (returns 429 MONTHLY_LIMIT_EXCEEDED with upgrade_url if exceeded)
URL format: url / icon / badge must be https:// only (400 INVALID_URL)

See Error Codes and Limits for the full list of error codes.

How It Works

REST API → Cloudflare Queues → Queue Consumer Worker → Browser Push

Notifications are enqueued immediately upon receiving the request. The Consumer Worker automatically starts and sends them asynchronously, so there are no timeouts even with a large number of subscribers.