REST API reference

Base URL: //api.pushnotificationservice.com/v1. All responses are JSON. The API is versioned in the path. A machine-readable OpenAPI 3.1 description of everything on this page is also available.

Authentication

Create an API key in the dashboard under API keys. The key is shown once. Store it securely. Authenticate with a bearer token:

Authorization: Bearer pns_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are pns_ followed by a 12-character prefix and a 40-character secret.

Keys are scoped to your account: you can only act on sites your account owns. Requests are rate-limited to 120/min per key. Unauthenticated requests get 401.

Send a notification

POST /v1/sites/{siteId}/notifications

Omitting both tags and subscribers targets all active subscribers. Omitting platforms targets every platform a subscriber is on — web, iOS, and Android. Omit these fields entirely to get that behavior — an empty array (e.g. "tags": []) is rejected with a 422 rather than treated the same as omitting the field.

Quota is checked once, when you create (or restore) a notification — never again after that. A scheduled notification, or one that's already sending, always completes against its full live audience, even if more subscribers join in the meantime: we don't cancel or truncate a send you've already started because your account grew. Only creating a new notification can be rejected with a 429 for insufficient quota, and only true deliveries count against your monthly quota — a failed send costs nothing.

curl -X POST \
  //api.pushnotificationservice.com/v1/sites/SITE_ID/notifications \
  -H "Authorization: Bearer pns_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Flash sale",
    "body": "30% off for the next hour.",
    "url": "https://example.com/sale",
    "tags": ["offers"]
  }'

{
  "data": {
    "id": "9b1f...",
    "title": "Flash sale",
    "status": "queued",
    "counts": { "targeted": 0, "delivered": 0, "displayed": 0, "failed": 0, "clicked": 0 }
  }
}

Delivery is asynchronous: the send returns queued (or scheduled) and the counts fill in as workers deliver. Poll the campaign endpoint below for live counts. delivered counts push-service acceptance; displayed counts notifications the service worker actually showed on a device.

Other notification endpoints

Subscribers

Mobile device tokens

Native iOS and Android apps register their own push token so campaigns can target them alongside (or instead of) web subscribers. These endpoints are public — no API key — the same way the SDK's web subscription endpoints are, since a native app has no Origin header for CORS to check against. Each site needs its APNs and/or FCM credentials configured once in the dashboard before sends actually deliver; registration itself is accepted either way, so a token is never lost to a timing gap.

curl -X POST \
  //api.pushnotificationservice.com/v1/sites/SITE_ID/device-tokens \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "ios",
    "token": "the 64-character hex APNs device token"
  }'

platform is ios or android. iOS tokens are 64-200 hex characters; Android (FCM) tokens are long base64url-ish strings. An optional bundle_id field, if sent, must match the site's configured APNs bundle ID or the request is rejected — a lightweight check against token stuffing, since there's no Origin header to rely on here.

tags cannot target device tokens (there's no per-device tagging yet) — a tag-scoped send only ever reaches web subscribers, and combining tags with platforms: ["ios"]/["android"] is rejected as a 422. The image field on a notification displays automatically on Android; on iOS it requires the app to ship its own Notification Service Extension (a standard APNs mutable-content requirement).

Signed links in notifications

Every delivered notification carries signed URLs generated per campaign or subscriber. You never build these yourself, but you'll see them in traffic and logs:

All of them verify a URL signature and reject tampered links with 403. The browser-facing subscription endpoints used by the SDK snippet (/v1/sites/{siteId}/config, /v1/sites/{siteId}/subscriptions…) are internal to the snippet and documented on the snippet page.

Errors & limits