Skip to content

API reference / API overview

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

https://api.meslzy.com/push/v1

Endpoints#

MethodPathAuthPurpose
POST/v1/notificationsAPI keySend a notification
GET/v1/notifications/{id}API keyGet a notification and its attempts
DELETE/v1/notifications/{id}API keyCancel a scheduled notification
POST/v1/hooks/{token}Hook tokenSend plain text with ntfy-style headers
POST/v1/hooks/{token}/discordHook tokenSend a Discord webhook body
POST/v1/hooks/{token}/slackHook tokenSend a Slack webhook body
POST/v1/hooks/{token}/appriseHook tokenSend an Apprise JSON body
GET/v1/connect/{token}Connect tokenRead a connect link
POST/v1/connect/{token}Connect tokenConnect a browser
POST/v1/eventsEvent tokenReport a shown, click, action or close event
POST/v1/browsers/{id}/disconnectEvent tokenDisconnect a browser

Authentication#

  • API key: the notification endpoints take Authorization: Bearer sk_live_… or sk_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 with 400 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:

HeaderMeaning
Content-Typeapplication/json on every response with a body, except the Slack hook, which answers in plain text like Slack does.
X-Request-IdA unique id like req_0199… for this request. Include it when you ask for help.
Cache-Controlno-store. Responses are never cached.
Retry-AfterOnly 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

Access-Control-Allow-Origin: *Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Allow-Headers: Authorization, Content-Type, Idempotency-Key, Title, Priority, Tags, ClickAccess-Control-Max-Age: 86400Access-Control-Expose-Headers: X-Request-Id, Retry-After
WarningOpen CORS does not mean live keys work from a browser. A request with an 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.