API overview

The base URL, the six endpoints, how each one authenticates and the conventions every response follows.

The Push API is a small JSON API over HTTPS. Two endpoints are for your server; the other four 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#

Method	Path	Auth	Purpose
POST	/v1/notifications	API key	Send a notification
GET	/v1/notifications/{id}	API key	Get a notification and its attempts
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 click, action or close
POST	/v1/browsers/{id}/disconnect	Event token	Disconnect 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.
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:

Header	Meaning
Content-Type	`application/json` on every response with a body.
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

Access-Control-Allow-Origin: *Access-Control-Allow-Methods: GET, POST, OPTIONSAccess-Control-Allow-Headers: Authorization, Content-Type, Idempotency-KeyAccess-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. Requests are limited per minute; see Rate limits.