Star
API reference

Event stream

Delivery outcomes as they happen, over server-sent events. Use it for dashboards and live status instead of polling the log.

Stream delivery events

GET/v1/events/stream

Auth: Project key, or the admin key or a session with x-project-id.

An open text/event-stream carrying the caller's project only. Browsers can't set headers on EventSource, so pass the key as ?token=. Use a read-only key for that.

Only delivery:delivered and delivery:failed are sent. Skips and throttling are in-process events on NotifkitServer (see Server).

Query parameters

NameTypeDefaultDescription
tokenstringAPI key, for clients that can't send headers.

Responses

200 OK The stream opens with a reconnect hint, then one event per outcome.

retry: 10000

event: delivery:delivered
data: {"taskId":"7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b","providerMessageId":"4f1e8b7c-2d3a-4e5b-9c6d-0a1b2c3d4e5f","channel":"email"}

event: delivery:failed
data: {"taskId":"7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:52b0f7c3-4d5e-4f6a-8b7c-9d0e1f2a3b4c","error":"Transport timeout after 10000ms","channel":"push"}
Common errors (401, 400, 429, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "internal_error"
}

Example

curl -N "http://localhost:3000/v1/events/stream?token=$NK_KEY"
const es = new EventSource("http://localhost:3000/v1/events/stream?token=" + readOnlyKey);
es.addEventListener("delivery:delivered", (e) => console.log(JSON.parse(e.data)));