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
| Name | Type | Default | Description |
|---|---|---|---|
token | string | API 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)));