`/v1/subscribe`

Project auth (?project= query param or X-LitePush-Project header). See Concepts → Authentication.

This is called from the user's browser. In normal use, you don't call it directly — the Browser SDK does. It's documented here for custom integrations (e.g. a native app shell, a server-side mirror, or debugging).

`POST /v1/subscribe`

What it does: Stores a browser's push subscription so LitePush can deliver pushes to it later. Idempotent on (project_id, endpoint) — calling it twice for the same browser just refreshes last_seen_at.

When to use it: Almost never. litepush.subscribe() in the browser SDK calls this for you with the right body. Call it manually only if you're (a) replacing the SDK with your own implementation, or (b) seeding subscribers from a server-side flow.

Authentication: Project — ?project= query param or X-LitePush-Project header.

Request body:

Field	Type	Required	Description
`endpoint`	string (URL, ≤ 2048 chars)	yes	The push gateway URL the browser handed back. From `PushSubscription.endpoint`.
`keys.p256dh`	string (≤ 256 chars)	yes	Base64url-encoded ECDH public key. From `PushSubscription.getKey('p256dh')`.
`keys.auth`	string (≤ 256 chars)	yes	Base64url-encoded auth secret. From `PushSubscription.getKey('auth')`.
`external_id`	string (≤ 256 chars)	no	Your own user ID. Lets you target this user across all their devices via `target: { type: 'user', external_id }`. May only contain letters, numbers, underscores, and hyphens (`A–Z a–z 0–9 _ -`) — anything else returns `400`.
`group_ids`	string (≤ 50 items)	no	Group IDs to assign this subscriber to at create time. Invalid IDs (typos, deleted groups, or IDs from another project) are silently dropped — the subscriber is still created with no membership in those groups. See note under Errors below.

Example:

curl -X POST 'https://api.litepush.dev/v1/subscribe?project=prj_xxxxxxxx' \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://fcm.googleapis.com/fcm/send/cZxJ...",
    "keys": {
      "p256dh": "BNcRdreALR...",
      "auth": "tBHItJI5sj..."
    },
    "external_id": "user_42",
    "group_ids": ["grp_01HXM..."]
  }'

Success — 201 Created:

{ "id": "sub_01HXM..." }

The returned id is the LitePush subscriber identifier — keep it if you want to manage group membership server-side later.

Errors:

400 missing_project — neither ?project= nor X-LitePush-Project was provided.
400 (validation) — body shape is wrong (e.g. endpoint isn't a URL, keys missing).
404 project_not_found — the project ID doesn't exist.
403 subscriber_limit_reached — the project is at its plan's subscriber cap. Returned with the cap value in the message.
429 rate_limited — see Concepts → Rate limits.

Invalid group_ids do NOT cause an error. They're silently dropped while the subscriber row is still created successfully. The choice is deliberate — failing the whole subscribe over a typo would block real users from opting in, and the SDK gives you no good recovery path. If initial group membership matters to you, fetch GET /v1/groups first to validate, or assign membership in a second call via POST /v1/groups/:id/subscribers (which DOES 404 on bad group IDs).