Devices
Register, update, and remove devices (FCM/APNS tokens) for push delivery.
Lists devices newest-first, optionally filtered by ?external_user_id= (exact) or ?search= (exact external_user_id OR substring match over tags; search takes precedence when both are present), paginated via ?limit=&cursor=.
Path Parameters
App ID
Query Parameters
Filter by external user ID (exact match; ignored when search is present)
Search by external user ID (exact) or tags (substring); takes precedence over external_user_id
Page size (1-100, default 50)
Pagination cursor
Response Body
application/json
curl -X GET "https://example.com/v1/apps/string/devices"{}Registers (upserts) a device token for the App. SDK-facing: authenticated by REST or Client key, never an admin session.
Path Parameters
App ID
Request Body
application/json
Device token, platform, and optional external user ID / tags
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/v1/apps/string/devices" \ -H "Content-Type: application/json" \ -d '{}'{ "app_id": "string", "created_at": "string", "external_user_id": "string", "id": "string", "platform": "string", "subscribed": true, "tags": { "property1": null, "property2": null }, "token": "string", "updated_at": "string"}Fetches a single device by ID, scoped to the App.
Path Parameters
App ID
Device ID
Response Body
application/json
curl -X GET "https://example.com/v1/apps/string/devices/string"{ "app_id": "string", "created_at": "string", "external_user_id": "string", "id": "string", "platform": "string", "subscribed": true, "tags": { "property1": null, "property2": null }, "token": "string", "updated_at": "string"}Updates a device's subscription flag, tags, or external user ID. When authenticated by a Client key, the request must also carry the device's own token as proof of ownership.
Path Parameters
App ID
Device ID
Request Body
application/json
Fields to update
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X PATCH "https://example.com/v1/apps/string/devices/string" \ -H "Content-Type: application/json" \ -d '{}'{ "app_id": "string", "created_at": "string", "external_user_id": "string", "id": "string", "platform": "string", "subscribed": true, "tags": { "property1": null, "property2": null }, "token": "string", "updated_at": "string"}Soft-deletes a device. Session-only (no REST/Client key path). Fails if the device still has delivery records.
Authorization
SessionAuth Path Parameters
App ID
Device ID
Response Body
curl -X DELETE "https://example.com/v1/apps/string/devices/string"