Live Activities

Starts an iOS Live Activity on every targeted device that has already registered a push-to-start token for {activity_type}. The path is mounted at the server root, not under /v1.

Auth. Authorization: Key <REST API key> or X-OP-API-Key. The Authorization header also accepts the Basic, Bearer and bare-value spellings, and in every one of them the raw REST key is taken as the literal text after the scheme word — Basic here is not RFC 7617 and nothing is base64-decoded.

Body. event must be "start". activity_id is required and cannot contain /. event_attributes (ActivityKit attributes) and event_updates (content-state) must both be non-empty objects. name is required and capped at 128 characters. contents and headings are required and must each carry a non-blank en entry. Optional: stale_date (unix seconds; a value at or above 1e11 is rejected as milliseconds), priority (5 or 10, default 10), ios_relevance_score (0–1), ios_sound/sound (first non-blank wins), and idempotency_key.

Targeting. Supply exactly one of include_aliases, include_subscription_ids, included_segments or filters; excluded_segments requires included_segments. Before anything is sent the server checks that at least one targeted device holds a push-to-start token for this activity type, and fails with 400 rather than reporting a send that reaches nobody.

Idempotency. idempotency_key is the only idempotency mechanism in OpenPush and it is a body field, not a header. It must be a UUID; a replay returns the original notification_id with Idempotent-Replayed: true and sends nothing; records are retained for 30 days.

Caveats. Unknown body keys return 400; is_ios, isAndroid, ios_interruption_level, apns_push_type_override, subtitle and custom_data are not implemented. Errors use this pair's own envelope, {"errors": ["…"]}, not detail. Rate limited to 60 requests per app per 60 seconds, shared with the update/end route.

Updates or ends an activity that is already running on devices. Targeting is fixed to the activity_id in the path — there are no segments, aliases or filters here, so every device still holding that activity is pushed. Mounted at the server root, not under /v1.

Auth. Authorization: Key <REST API key> or X-OP-API-Key, exactly as on the start route.

Body. event must be "update" or "end". event_updates (the new content-state) is required and non-empty on an end too. name is required, 128 characters or fewer. contents and headings are optional, but if present must carry a non-blank en entry. stale_date is accepted on both events; dismissal_date is end-only and is a 400 on an update. Optional priority (5 or 10), ios_relevance_score (0–1) and sound/ios_sound.

Not honoured here. idempotency_key is start-only — a retried update or end pushes again. Unknown body keys return 400. Errors use this pair's own envelope, {"errors": ["…"]}. Rate limited to 60 requests per app per 60 seconds, shared with the start route.

An activity that has ended can never be updated again: both the pre-flight and a fan-out that reaches nobody answer 404.

Registers an ActivityKit update token so the server can push updates to one Live Activity on one device. A dedicated route rather than an ingest event type, because a wrong field here means a lock screen that silently never updates — this route names the field that was wrong.

The device must already be registered: an unknown push token is a 404. The platform window is reported back in the response — updates are accepted for 8 hours from started_at, and an end for 4 hours after that, whatever the server does.

Registers an iOS 17.2+ push-to-start token, which starts an activity that does not exist yet. The platform issues one token per activity type, so activity_type is required and the token is stored keyed by it — there is no activity id and no window to age it out.

Removes this device's push-to-start token for one activity type. A type this device has no token for is a 404, so a caller can tell a removal from a no-op.

Attributes a tap on a Live Activity back to the push that produced it. Every tap increments the message's click total, while the per-delivery click timestamp is kept first-write-wins so distinct-device funnel numbers stay honest.

Pass notification_id to attribute a specific push; without it the most recent Live Activity push delivered to this device for this activity is used. If no such push exists, the click is a 404 rather than being attributed to nothing.

The device reports that one of its own activities is over. An activity id that belongs to another device is a 404, not a silent success — "we ended it" and "you do not have one by that name" are different answers.