Register a push device.

POST

/api/v1/devices

Registers (or refreshes) the calling user’s device for push notifications. The push token is the identity: re-sending an existing token — even from a different account — transfers ownership so a recycled device never receives the previous user’s notifications. Idempotent; safe to call on every app launch.

Authorizations

• default

Request Body ^required

object

platform

required

OS family. One of ios, android, web.

string

ios

provider

required

Push transport. One of fcm, expo, apns.

string

fcm

push_token

required

The provider-issued push token.

string

fGc1...token

device_id

Optional stable client device identifier.

string

nullable

7B3F2A10-...

device_name

Optional human-readable device label.

string

nullable

John's iPhone

app_version

Optional client app version.

string

nullable

1.4.2

Responses

201

object

data

object

id

string

01HX...

platform

string

ios

provider

string

fcm

device_name

string

John's iPhone

last_used_at

string

2026-05-17T10:00:00+00:00

{
  "data": {
    "id": "01HX...",
    "platform": "ios",
    "provider": "fcm",
    "device_name": "John's iPhone",
    "last_used_at": "2026-05-17T10:00:00+00:00"
  }
}