/v1/subscribers

Bearer auth. See Concepts → Authentication.

These endpoints exist primarily to honour GDPR data-subject requests. Under GDPR you (the data controller) own the relationship with your end users; LitePush is the data processor. When one of your users invokes their rights, you handle the request — these calls let you satisfy it. The full controller-processor terms are in the Data Processing Addendum.

For restriction / objection (stop delivery without deleting history), use the project-authed POST /v1/unsubscribe instead — it flips status='unsubscribed' but keeps the row for analytics. The endpoints below hard-delete.

DELETE /v1/subscribers/by-endpoint

What it does: Hard-deletes the subscriber row matching (project_id, endpoint). Event rows and group memberships cascade away via foreign key.

When to use it: GDPR Article 17 (right to erasure) when the data subject hands you their device's push endpoint URL.

Request body:

Example:

curl -X DELETE https://api.litepush.dev/v1/subscribers/by-endpoint \
  -H "Authorization: Bearer lpk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint": "https://fcm.googleapis.com/fcm/send/cZxJ..." }'

Success — 200 OK:

{ "deleted": 1 }

deleted is 0 if no subscriber matched.

DELETE /v1/subscribers/by-external-id/:eid

What it does: Hard-deletes every subscriber row in this project that carries the given external_id — covers users with multiple devices.

When to use it: GDPR Article 17 when you only have your own user ID and want to wipe their LitePush footprint in one call. Common pattern: wire this into your user-deletion handler so deleting a user in your DB also deletes them from LitePush.

Authentication: Bearer.

Path parameter:

Example:

curl -X DELETE https://api.litepush.dev/v1/subscribers/by-external-id/user_42 \
  -H "Authorization: Bearer lpk_live_xxxxxxxx"

Success — 200 OK:

{ "deleted": 2 }

Errors:

• 400 invalid_external_id — empty, longer than 256 chars, or containing characters outside A–Z a–z 0–9 _ -.

GET /v1/subscribers/export

What it does: Streams a CSV of every active subscriber in the project, with their group memberships joined in.

When to use it: GDPR Article 20 (right to portability), bulk inspection, or your own data warehousing.

Authentication: Bearer.

Example:

curl https://api.litepush.dev/v1/subscribers/export \
  -H "Authorization: Bearer lpk_live_xxxxxxxx" \
  -o subscribers.csv

Success — 200 OK: CSV body, Content-Type: text/csv; charset=utf-8, Content-Disposition: attachment; filename="litepush-subscribers-<project_id>.csv".

CSV columns:

The dashboard exposes the same export under Project → Subscribers → Export CSV.

Wiring erasure into your user lifecycle

A common pattern — in your own user-deletion handler, also wipe the user's LitePush rows so they stop receiving pushes and we don't keep their endpoint URL:

async function deleteUser(userId: string) {
  // Your usual cleanup
  await db.users.delete({ id: userId });

  // Also wipe their LitePush subscriber row(s). encodeURIComponent guards
  // against user IDs that happen to contain '/', '&', or whitespace.
  await fetch(
    `https://api.litepush.dev/v1/subscribers/by-external-id/${encodeURIComponent(userId)}`,
    {
      method: "DELETE",
      headers: { Authorization: `Bearer ${process.env.LITEPUSH_API_KEY}` },
    }
  );
}

Data we hold

For every active subscriber we store:

• Push endpoint URL (browser-issued)
• p256dh + auth encryption keys
• User-Agent at subscribe time (diagnostics)
• Optional external_id you provided
• Group memberships
• Per-event metadata (broadcast id, delivery / click / failure timestamps)

We do not store IP addresses, names, or fingerprinting data. Full list in the Privacy Policy §3.