Devices
Operações
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).
Autorizações
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parâmetros
Parâmetros de Caminho
App ID
Parâmetros de Consulta
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
Respostas
{"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.
Autorizações
App REST key (rk_...). Server-to-server calls.
App Client key (ck_...). Device-facing calls only.
Parâmetros
Parâmetros de Caminho
App ID
Corpo da Requisição
Respostas
Created
Summarize an app's devices
Returns lifetime device counts for an App: total, per platform, and per subscription state (soft-deleted devices excluded).
Autorizações
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parâmetros
Parâmetros de Caminho
App ID
Respostas
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.
Autorizações
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parâmetros
Parâmetros de Caminho
App ID
Respostas
{"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.
Autorizações
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parâmetros
Parâmetros de Caminho
App ID
Device ID
Respostas
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.
Autorizações
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
Parâmetros
Parâmetros de Caminho
App ID
Device ID
Respostas
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.
Autorizações
App REST key (rk_...). Server-to-server calls.
App Client key (ck_...). Device-facing calls only.
Parâmetros
Parâmetros de Caminho
App ID
Device ID
Corpo da Requisição
Respostas
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.
Autorizações
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
App REST key (rk_...). Server-to-server calls.
Parâmetros
Parâmetros de Caminho
App ID
Device ID
Parâmetros de Consulta
Page size (1-20, default 6)
Respostas
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.
Autorizações
Admin session cookie set by POST /v1/auth/login. Dashboard-only management.
Parâmetros
Parâmetros de Caminho
App ID
Device ID
Corpo da Requisição
Respostas
{"delivery_id": string, "status": "pending"}