Devices API

Method	Path	Auth	Purpose
PUT	/devices/:token	Token	Register or refresh a push token for the caller.
DELETE	/devices/:token	Token	Unregister a push token.

The push channel fans an alert out to every device token registered to the watch’s owner. The Android app calls these routes for you on sign-in and whenever the platform rotates its token; you only need them if you are building your own client.

Register a device

curl -s -X PUT "https://<your-host>/devices/<registration-token>" \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"platform":"android"}'

The token is the path parameter. platform currently accepts android only. Registration is an upsert keyed on owner plus token, so repeating it is safe and is the intended way to refresh a token.

Unregister a device

curl -s -X DELETE "https://<your-host>/devices/<registration-token>" \
  -H "authorization: Bearer $TOKEN"

{ "deleted": true }

Behaviour worth knowing

Note

• Tokens the push provider reports as gone are pruned automatically when a delivery is attempted, so uninstalled devices clean themselves up.
• Delivery succeeds if at least one device accepts the message.
• If the owner has no registered devices, delivery is treated as a failure — which means the alert is queued and retried rather than silently dropped. A push-only watch on an account with no device will therefore keep producing notify-failed until a device registers.

Payload shape

Messages are data-only on purpose: the app renders the notification itself, so device-side preferences such as alert tiers and quiet hours are honoured even when the app is backgrounded.

{
  "type": "alert",
  "watchId": "framework-releases",
  "watchName": "Framework stable releases",
  "title": "Framework stable releases",
  "summary": "Version 2.0 was released as stable.",
  "tier": "strong",
  "confidence": "0.86",
  "evidenceUrl": "https://example.com/blog/v2-ga"
}

All values are strings, as the push transport requires, and the summary is capped so the payload stays well within the transport’s size limit.