Notifications
Operations
List notifications for an app
Lists notifications newest-first, optionally filtered by ?status=, paginated via ?limit=&cursor=.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Query Parameters
Filter by status: pending, scheduled, cancelled, sent, partial_failure, failed
Filter by source: api, dashboard, mcp
Case-insensitive substring search across campaign name, title, and body (max 200 characters)
Filter by label; repeatable for AND (case-insensitive)
Page size (1-100, default 50)
Pagination cursor
Responses
{"items": [notificationResponse], "next_cursor": string|null}
Send a notification
Creates a Notification targeting devices, a segment, or an external user, and enqueues delivery (or schedules it for send_at). Either template_id, both ad_hoc_title/ad_hoc_body, or data_only with a non-empty data payload is required. Repeating the same Idempotency-Key header returns the original notification instead of creating a duplicate. target_value accepts at most 50,000 values and the request body at most 5 MiB.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Header Parameters
Idempotency key; a repeated key returns the original notification
Path Parameters
App ID
Request Body
Responses
Returned instead of 201 when the same Idempotency-Key was already used
Summarize an app's notifications by status
Returns lifetime per-status notification counts for an App: all, sent, scheduled, failed.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Responses
OK
Get a notification
Fetches a single Notification by ID, scoped to the App.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Notification ID
Responses
OK
Cancel a scheduled notification
Cancels a Notification that is still in "scheduled" state. Fails if the notification is not in that state.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Notification ID
Responses
OK
Edit a scheduled notification
Edits a Notification that is still in "scheduled" state, in place. Only the fields sent change; a field sent as null is cleared where that is valid (subtitle, image_url, data, labels, options, template_id, ad_hoc_title, ad_hoc_body). target_type may switch among device_ids, external_user_ids and segment_id, and is sent together with target_value. send_at must be in the future. The body accepts an optional version: when it differs from the stored version the call fails with 409 version_conflict and changes nothing; without it the last write wins: an edit that collides with another is retried, and only after repeated collisions does the call fail with 409 version_conflict. A body with no field to change is rejected with 422 invalid_body. Returns 422 not_scheduled once the notification was released or cancelled, or its send_at has passed. source cannot be edited. Same validation, target_value limit of 50,000 values and 5 MiB body limit as creating.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Notification ID
Request Body
Responses
OK
List a notification's deliveries
Lists the per-device delivery attempts and their status for a Notification, paginated via ?limit=&cursor=.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Notification ID
Query Parameters
Max items per page (default 50)
Pagination cursor
Responses
{"items": [deliveryResponse], "next_cursor": string|null}
Summarize a notification's deliveries
Returns the per-status delivery counts and a per-error breakdown of failed deliveries for a Notification.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parameters
Path Parameters
App ID
Notification ID
Responses
OK
Report a notification engagement event
Reports a received, opened, or clicked event against a notification, authenticated by Client key with the device's token as ownership proof. Device-facing only. Overview analytics count a sent delivery as opened when it has an opened or clicked event.
Authorizations
App Client key (ck_...). Device-facing calls only.
Parameters
Path Parameters
App ID
Notification ID
Request Body
Responses
Created