Overview
Push sends a native browser notification to a person with one HTTP request.
Push sends native browser notifications over the Web Push standard. Your server makes one HTTP request, or any tool calls a hook URL, and the browsers the person connected show the notification. There is no app to install, no phone number and no SDK.
How it works#
- Create a project in the dashboard. It holds your API keys and your recipients.
- Add a recipient: a name like
opsorsarathat stands for a person or a team. - The person opens a connect link and clicks Enable notifications. Their browser is now connected to the recipient.
- Your server calls
POST /v1/notificationswith the recipient's name. Push creates one attempt per connected browser, following the recipient's delivery policy, and hands each one to that browser vendor's push service.
Key ideas#
| Term | Meaning |
|---|---|
| Project | Owns API keys, recipients and connect links. Push manages its sending keys for you. Usage is counted per account, across all its projects. |
| API key | A secret your server sends as a bearer token. sk_live_… keys send; sk_test_… keys validate and record but send nothing. |
| Recipient | A named destination inside a project. You send to the name, never to a device. |
| Browser | One browser on one device that a person connected to a recipient. A recipient can have several. |
| Hook | A secret URL for one recipient that turns plain text or a Discord, Slack or Apprise request into a notification. |
| Notification | One accepted POST /v1/notifications request. |
| Attempt | One notification to one connected browser. Attempts are what Push bills and what carry a status. |
What Push can and cannot tell you#
Push learns that a browser vendor's push service accepted a message. Push's service worker then reports when the browser showed the notification and when the person clicked or dismissed it, so those are certain when present. See Statuses.
Base URL#
Every API path in these docs is relative to this base URL. All requests use HTTPS and JSON.
⫻
base URL
NoteNotifications show as coming from
meslzy.com, because that is the site the person allowed. That address never changes, so connected browsers stay connected.Where to go next#
- Quickstart: send your first notification in about two minutes.
- Sending notifications: the request, the response and what happens after.
- Delivery policy: all browsers at once, or one at a time with a fallback.
- Hooks and Shell one-liners: notifications from tools and scripts without writing code.
- API reference: every endpoint with its request, response and errors.