API concepts

Base URL: https://api.litepush.dev. All endpoints accept and return JSON unless otherwise stated.

This section is a reference, not a tutorial. If you're integrating for the first time, start with Getting started instead. Each endpoint path has its own page in the sidebar — this page covers the shared concepts they all build on.

Glossary

Quick glossary so the field names across the endpoint pages make sense.

Authentication

LitePush uses two auth styles depending on whether the caller is your server or a browser.

Server-to-server — Bearer token

Server endpoints (anything you call from your backend) require your API key in the Authorization header:

Authorization: Bearer lpk_live_xxxxxxxx

Endpoints requiring Bearer auth: GET /v1/me, POST /v1/send, all /v1/broadcasts* (read, list, cancel), all /v1/groups/*, all /v1/subscribers/*.

A missing, malformed, or revoked key returns 401 invalid_api_key.

Browser — Project query parameter

Three endpoints are called from a browser (the SDK and the service worker): /v1/subscribe, /v1/unsubscribe, /v1/events. These can't carry your secret API key — anyone would see it in DevTools — so they identify the project by its public ID instead:

?project=prj_xxxxxxxx

Or as a header (the SDK uses the header automatically):

X-LitePush-Project: prj_xxxxxxxx

http://localhost origins are not accepted by the API. If you're developing against the endpoint, tunnel your dev server through Cloudflare Tunnel or ngrok and register the tunnel's HTTPS hostname as your project's origin.

Project IDs are public by design — they ship in your client-side <script> tag and are visible in DevTools, like a publishable key, and that's fine: they're meant to be public. The only real secret is your API key (the lpk_live_… Bearer token) — keep that server-side, and rotate it from the dashboard if it ever leaks.

If you have a use case for server-side authoritative subscribe (seeding subscribers from your backend rather than from a real browser) — there isn't a Bearer-authed equivalent of /v1/subscribe today. Email support@litepush.dev and tell us your shape.

Quick reference

Error format

Every error response uses the same envelope so your code can branch on error.code:

{
  "error": {
    "code": "monthly_push_limit_reached",
    "message": "Project would exceed the hobby plan cap of 200,000 pushes/month. This broadcast would add ~5,000."
  }
}

• code is a stable machine-parsable identifier. Treat it as your contract.
• message is human-readable and may change between releases. Show it in dashboards / debug pages, but don't string-match it in code.

Rate limits

Each project is capped at 600 requests/minute across all /v1/* endpoints.

On overage you get:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{ "error": { "code": "rate_limited", "message": "Project is over its per-minute API quota." } }

If you're consistently hitting this, you're almost certainly fan-outing from client-side code that should be batched into a server-side cron — email support@litepush.dev and we'll help architect a fix.

Status codes used