API overview
The base URL, every endpoint, how each one authenticates and the conventions every response follows.
The Push API is a small JSON API over HTTPS. The notification and hook endpoints are for your server and your tools; the rest are called by Push's own connect page and service worker, and are documented here for completeness.
Base URL#
⫻
base URL
Endpoints#
| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | /v1/notifications | API key | Send a notification |
| GET | /v1/notifications/{id} | API key | Get a notification and its attempts |
| DELETE | /v1/notifications/{id} | API key | Cancel a scheduled notification |
| POST | /v1/hooks/{token} | Hook token | Send plain text with ntfy-style headers |
| POST | /v1/hooks/{token}/discord | Hook token | Send a Discord webhook body |
| POST | /v1/hooks/{token}/slack | Hook token | Send a Slack webhook body |
| POST | /v1/hooks/{token}/apprise | Hook token | Send an Apprise JSON body |
| GET | /v1/connect/{token} | Connect token | Read a connect link |
| POST | /v1/connect/{token} | Connect token | Connect a browser |
| POST | /v1/events | Event token | Report a shown, click, action or close event |
| POST | /v1/browsers/{id}/disconnect | Event token | Disconnect a browser |
Authentication#
- API key: the notification endpoints take
Authorization: Bearer sk_live_…orsk_test_…. See Authentication. - Connect token: the connect endpoints take no key. The
cl_…token in the path is the credential, so treat a connect link like a password until it is used. - Hook token: the hook endpoints take no key. The
hk_…token in the path is the credential and is bound to one recipient, so treat a hook URL like an API key. See Hooks. - Event token: the events and disconnect endpoints take no key. Each connected browser gets its own
eventToken, which only works for that browser.
Requests#
- Request bodies are JSON. Send
Content-Type: application/json. A body may be at most 16,384 bytes; a larger one fails with400 VALIDATION_ERROR. - A trailing slash on the path is ignored.
- An unknown path, or a known path with the wrong method, returns
404 NOT_FOUND.
Responses#
Every response, success or error, carries these headers:
| Header | Meaning |
|---|---|
| Content-Type | application/json on every response with a body, except the Slack hook, which answers in plain text like Slack does. |
| X-Request-Id | A unique id like req_0199… for this request. Include it when you ask for help. |
| Cache-Control | no-store. Responses are never cached. |
| Retry-After | Only on 429 RATE_LIMITED: the seconds to wait before retrying. |
- Timestamps are ISO 8601 strings in UTC, such as
2026-10-05T09:12:44.120Z. - Ids of notifications, attempts, browsers and recipients are UUIDs.
- A value that is not known yet is
null, never missing.
CORS#
The API answers browser requests from any origin, because the connect page and service worker call it. Preflight OPTIONS requests get 204 with:
⫻
CORS headers
Origin header and a live key is refused with 403 FORBIDDEN; test keys still work, so you can try the API from a page. An API key in browser code is public. Call the notification endpoints from your server only.Errors and limits#
Every error uses the same error format with a stable code, except the Discord and Slack hooks, which answer errors the way Discord and Slack do so existing tools understand them. Requests are limited per minute; see Rate limits.