Devices
Operations
List devices for an app
Lists devices for an app. Filters: ?q= (external_user_id/id substring, exact token, or key:value tags), ?status= (ok|off|invalid), ?platform= (ios|android|web), ?activity= (active|inactive), ?sort= (last_seen|first_seen), plus the legacy ?external_user_id=, ?search= and ?subscribed=. ?include=counts adds total, per-status counts and version meta on the first page only (no 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
Search: external_user_id or id substring, exact push token, or key:value tag
Filter by derived push status: ok, off or invalid
Filter by platform: ios, android or web
Activity filter: active (seen in 7 days) or inactive (30d+ or never)
Sort: last_seen or first_seen (default created_at)
Comma-separated extras; counts adds total, per-status counts and meta (first page only)
Filter by external user ID (exact match; ignored when search is present)
Search by device ID (substring) or external user ID (exact) or tags (substring); takes precedence over external_user_id
Filter by subscription state: true or false
Page size (1-100, default 50)
Pagination cursor
Responses
{"items": [deviceResponse], "next_cursor": string|null, "total": int, "counts": {all, ok, off, invalid}} (total, counts and meta only with include=counts and no cursor)
Register a device
Registers (upserts) a device token for the App. SDK-facing: authenticated by REST or Client key, never an admin session. On re-registration of an existing token, omitted external_user_id and tags keep their stored values; an explicit empty tags object clears tags.
Authorizations
App REST key (rk_...). Server-to-server calls.
App Client key (ck_...). Device-facing calls only.
Parameters
Path Parameters
App ID
Request Body
Responses
Created
Summarize an app's devices
Returns lifetime device counts for an App: total, per platform, and per subscription state (soft-deleted devices excluded).
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
List distinct tag keys for an app's devices
Returns the distinct tag keys in use across an App's devices, each with up to 10 distinct sample values, capped at 200 keys.
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
{"keys": [tagKeyResponse]}
Get a device
Fetches a single device by ID, scoped to the App, with matched segments, 30-day sends, push status, token error and version metadata.
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
Device ID
Responses
OK
Delete a device
Soft-deletes a device. Session-only (no REST/Client key path). Its delivery history is kept; the device disappears from lists and segments.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
Parameters
Path Parameters
App ID
Device ID
Responses
No Content
Update a device
Updates a device's subscription flag, tags, external user ID, app version, session telemetry, country, or profile fields (device_os, device_model, sdk_version, sdk_name, permission_status, last_unsubscribed_at, email, phone, timezone_id, language). Absent fields are unchanged. external_user_id, country, email and phone accept null to clear the stored value; an empty external_user_id ("") is unchanged. When authenticated by a Client key, the request must also carry the device's own token as proof of ownership.
Authorizations
App REST key (rk_...). Server-to-server calls.
App Client key (ck_...). Device-facing calls only.
Parameters
Path Parameters
App ID
Device ID
Request Body
Responses
OK
List a device's recent deliveries
Returns the device's deliveries from the last 30 days, newest first, scoped to the App. status is delivered|opened|failed|pending; reason is the classified provider error code of a failed delivery (null otherwise); is_test marks a dashboard test send; template_name is null for an ad-hoc 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
Device ID
Query Parameters
Page size (1-20, default 6)
Responses
OK
Send a test push to a device
Session-only. Creates an is_test notification and delivery for the device and enqueues it through the normal queue. 422 device_not_reachable when the device cannot receive push; 429 beyond 10/min per user and app.
Authorizations
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
Parameters
Path Parameters
App ID
Device ID
Request Body
Responses
{"delivery_id": string, "status": "pending"}