This is how the pieces work together. Setup is in the Quickstart, the exact requests are in the API reference.
The flow
- The app registers. The SDK (or Expo) reports the device’s push-to-start token and
your user ID. The attributes struct has an optional
lacId, which we fill in when we start the activity by push. - Your backend starts it.
POST /api/v1/activitieswith the user, the attributes type and the content state. Leave outstartAtto start now. It is in milliseconds. We send push-to-start at that time to every device of the user (iOS 17.2+). On iOS 26,LiveActivity.schedule(…)in the app also schedules it on the device, and we push only if the device hasn’t reported it 60 seconds afterstartAt. - Your backend updates and ends it.
PATCH /api/v1/activities/act_…with a new content state,POST …/endto end it,DELETE …to cancel it before it starts. - The phone reports back. The SDK tells us when the activity is on the phone, gets a new token, ends or is dismissed. We pass that to your backend as webhooks.
curl https://liveactivity.dev/api/v1/activities \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{
"appId": "<app id>",
"userId": "user_42",
"attributesType": "DeliveryAttributes",
"attributes": { "orderId": "1234" },
"contentState": { "eta": 15, "status": "cooking" },
"startAt": 1795180000000,
"alert": { "title": "Your order", "body": "Cooking now" }
}'
What we take care of
- Tokens. Every activity has its own update token, and the push-to-start token rotates. The SDK reports each new one, and devices that got their token late catch up on the latest state.
- Payloads. Content state is checked against what your app’s
ContentStatesends (same keys, same JSON types) and against APNs’ 4 KB limit. A mismatch returns 422, where iOS would otherwise drop the update silently. Dates: Swift’s defaultCodableencodesDateas seconds since 2001, so send numbers your struct expects. - Budget. Updates go at priority 5. Only updates with an
alertuse priority 10, which counts against Apple’s hourly budget. Rapid updates collapse into the newest one. - Timeline. Activities shows every push, APNs answer and SDK report for each activity. See Troubleshooting.
Something not arriving? Start with Troubleshooting.