`/v1/broadcasts`

Bearer auth. See Concepts → Authentication. Every endpoint here is scoped to the key's project — you only ever see or touch your own broadcasts.

The broadcast object

GET /v1/broadcasts/:id and each entry in GET /v1/broadcasts return this shape:

Field	Type	Description
`id`	string	The `bdc_*` ID.
`status`	string	`pending` (queued) → `sending` (fanning out) → `sent` / `failed`. `canceled` if a scheduled broadcast was cancelled before firing.
`source`	string	`api` or `dashboard` — where it originated.
`target`	object	The audience selector, same shape as in `/v1/send`.
`notification`	object	`{ title, body, icon, image, url }`. `icon`/`image`/`url` are `null` when unset.
`ttl`	number \| null	The `ttl` it was sent with, or `null` if the default was used.
`urgency`	string \| null	The `urgency` it was sent with, or `null` for the default.
`topic`	string \| null	The `topic` it was sent with, or `null`.
`delivered_count`	number	Pushes accepted by the push gateway.
`failed_count`	number	Pushes that failed (dead subscription, gateway error, retries exhausted).
`scheduled_at`	number \| null	Scheduled fire time (Unix ms), or `null` for an immediate send.
`started_at`	number \| null	When fan-out began (Unix ms), or `null` if it hasn't.
`finished_at`	number \| null	When fan-out finished (Unix ms), or `null` if not done.
`created_at`	number	When the broadcast was created (Unix ms).

What it does: Reads a single broadcast — its status, delivered/failed counts, the delivery options it was sent with, and its timestamps. Poll this after POST /v1/send to watch a broadcast progress from pending to sent.

Authentication: Bearer.

Path parameter:

Param	Required	Description
`:id`	yes	The `bdc_*` ID returned by `POST /v1/send`.

Example:

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

Success — 200 OK:

{
  "id": "bdc_01HXM...",
  "status": "sent",
  "source": "api",
  "target": { "type": "all" },
  "notification": { "title": "New post", "body": "Read more", "icon": null, "image": null, "url": "https://myblog.com/p/1" },
  "ttl": null,
  "urgency": null,
  "topic": null,
  "delivered_count": 1280,
  "failed_count": 3,
  "scheduled_at": null,
  "started_at": 1717200000000,
  "finished_at": 1717200004000,
  "created_at": 1717200000000
}

Errors:

404 broadcast_not_found — no broadcast with that ID exists in this project.

`GET /v1/broadcasts`

What it does: Lists the project's broadcasts, most recent first.

Authentication: Bearer.

Query parameters:

Param	Type	Default	Description
`limit`	number (1–100)	`20`	Max broadcasts to return.
`offset`	number (≥ 0)	`0`	Broadcasts to skip, for paging.

Example:

curl "https://api.litepush.dev/v1/broadcasts?limit=20&offset=0" \
  -H "Authorization: Bearer lpk_live_xxxxxxxx"

Success — 200 OK:

{
  "broadcasts": [ { "id": "bdc_01HXM...", "status": "sent", "...": "..." } ],
  "total": 137,
  "limit": 20,
  "offset": 0
}

total is the project's full broadcast count (ignores limit/offset) — use it to page: keep requesting with a rising offset until offset + broadcasts.length >= total.

Errors:

400 — limit outside 1–100, or a negative offset.

`DELETE /v1/broadcasts/:id`

What it does: Cancels a scheduled broadcast that hasn't fired yet (one created with scheduled_at). Immediate broadcasts can't be canceled — they're already fanning out.

When to use it: You scheduled a broadcast for later (via POST /v1/send with scheduled_at) and want to call it off before it sends.

Authentication: Bearer. Scoped to the key's project — you can only cancel your own.

Path parameter:

Param	Required	Description
`:id`	yes	The `bdc_*` ID returned when the broadcast was scheduled.

Example:

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

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

Errors:

409 not_cancelable — the broadcast already fired, was already canceled, isn't a scheduled broadcast, or doesn't exist in this project.