/v1/groups

Bearer auth. See Concepts → Authentication.

Groups are named segments scoped to a project. A subscriber can be in any number of groups; a group can hold any number of subscribers. Broadcasts can target a single group via POST /v1/send with target: { type: "group", group_id }.

Per-plan limits

Hitting the cap returns 403 group_limit_reached on create.

Assigning subscribers

There are two ways to put a subscriber in a group:

• At subscribe time — pass group_ids in the POST /v1/subscribe body. Invalid IDs are silently dropped (the subscriber is still created).
• After subscribe, from your server — POST /v1/groups/:id/subscribers (below). This is the path the browser SDK flow uses: litepush.subscribe() returns the subscriber's ID, then your server assigns groups. Keeping membership management server-side stops a tampered client from joining itself to arbitrary groups.

GET /v1/groups

What it does: Lists every group in this project, with its current member count.

Example:

curl https://api.litepush.dev/v1/groups \
  -H "Authorization: Bearer lpk_live_xxxxxxxx"

Success — 200 OK:

{
  "groups": [
    { "id": "grp_01HXM...", "name": "newsletter", "description": "Weekly readers", "member_count": 1284, "created_at": 1716762345123 },
    { "id": "grp_01HXN...", "name": "product-updates", "description": null, "member_count": 312, "created_at": 1716762400000 }
  ]
}

POST /v1/groups

What it does: Creates a named group. Plan-gated — see Per-plan limits above.

Request body:

Example:

curl -X POST https://api.litepush.dev/v1/groups \
  -H "Authorization: Bearer lpk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "newsletter", "description": "Weekly post readers" }'

Success — 201 Created:

{ "id": "grp_01HXM..." }

Errors:

• 403 group_limit_reached — at your plan's group cap.
• 409 group_name_taken — another group in this project already uses that name.

PATCH /v1/groups/:id

What it does: Renames a group or updates its description. Both fields are optional; sending neither is a no-op.

Request body:

Example:

curl -X PATCH https://api.litepush.dev/v1/groups/grp_01HXM... \
  -H "Authorization: Bearer lpk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "weekly-newsletter" }'

Success — 200 OK: { "ok": true }

Errors:

• 404 group_not_found.
• 409 group_name_taken.

DELETE /v1/groups/:id

What it does: Deletes the group. Memberships cascade away. Subscribers themselves are untouched — they just lose this one segment.

Example:

curl -X DELETE https://api.litepush.dev/v1/groups/grp_01HXM... \
  -H "Authorization: Bearer lpk_live_xxxxxxxx"

Success — 200 OK: { "ok": true }

Errors:

• 404 group_not_found.

POST /v1/groups/:id/subscribers

What it does: Adds subscribers to a group. Idempotent — re-adding existing members is a no-op. Subscriber IDs from other projects are silently filtered out.

Request body:

Example:

curl -X POST https://api.litepush.dev/v1/groups/grp_01HXM.../subscribers \
  -H "Authorization: Bearer lpk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "subscriber_ids": ["sub_01HXM...", "sub_01HXN..."] }'

Success — 200 OK:

{ "added": 2 }

added is the count actually inserted — subscribers already in the group don't double-count.

Errors:

• 404 group_not_found.

DELETE /v1/groups/:id/subscribers/:sid

What it does: Removes one subscriber from one group. Removes only the membership; the subscriber row stays in other groups and remains active.

Example:

curl -X DELETE https://api.litepush.dev/v1/groups/grp_01HXM.../subscribers/sub_01HXM... \
  -H "Authorization: Bearer lpk_live_xxxxxxxx"

Success — 200 OK: { "ok": true }

Errors:

• 404 group_not_found.