PushNotifications.org Web Push REST API documentation

The versioned API uses account bearer tokens and the same ownership, destination, audience, allowance, and scheduling checks as the dashboard. It can create drafts or schedules, but it cannot grant browser permission.

Make your first authenticated request

Generate a token in API & MCP settings, store it outside source control, and send it only in the Authorization header. The token is displayed once and stored as a one-way hash.

List registered websitescurl --fail-with-body \ -H "Authorization: Bearer $PUSHNOTIFICATIONS_TOKEN" \ https://pushnotifications.org/api/v1/sites

Available resources

Websites

GET /sites returns the account-owned numeric site IDs required by campaign calls.

Overview

GET /overview returns delivery usage, campaign totals, and the next scheduled campaign.

Campaigns

GET /campaigns lists work; POST /campaigns creates a draft or validated schedule.

One campaign

GET or PATCH /campaigns/{id} reviews or edits an account-owned draft or schedule.

Create a reviewable campaign draft

Start with status: draft. Use a site ID returned by /sites, keep the destination on that verified website, and review the result before scheduling.

POST /api/v1/campaigns{ "site_id": 42, "title": "The November guide is ready", "body": "Read the new guide and save the checklist.", "target_url": "https://example.com/guides/november", "status": "draft", "targeting": { "devices": ["desktop", "phone"], "browsers": ["chrome", "safari"] } }

Add images and actions where supported

An optional public HTTPS image and up to two action buttons can be included. Browser and operating-system support varies; the title, message, and main destination remain the fallback.

Rich fields{ "image_url": "https://example.com/images/guide.webp", "actions": [ {"label": "Read guide", "url": "https://example.com/guides/november"}, {"label": "View checklist", "url": "https://example.com/checklist"} ] }

What the API will reject

  • Unowned website IDs and destinations outside the registered origin.
  • Invalid, unsafe, or non-HTTPS public destinations.
  • Unsupported audience values, oversized copy, and malformed schedules.
  • Edits to campaigns that have already entered a non-editable delivery state.
  • Requests beyond the account's enforced delivery allowance.

See the MCP server for typed AI-client tools or use the command-line client for terminal workflows.