# Live Activities

> How starting, updating and ending Live Activities works, from your backend to the phone.

Updated 2026-11-21

This is how the pieces work together. Setup is in the [Quickstart](/docs/quickstart), the exact requests are in the
[API reference](/docs/api).

## The flow

1. **The app registers.** [The SDK](/docs/swift) (or [Expo](/docs/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.
2. **Your backend starts it.** `POST /api/v1/activities` with the user, the attributes type and the content state.
   Leave out `startAt` to 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 after `startAt`.
3. **Your backend updates and ends it.** `PATCH /api/v1/activities/act_…` with a new content state,
   `POST …/end` to end it, `DELETE …` to cancel it before it starts.
4. **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](/docs/webhooks).

```sh
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 `ContentState` sends (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
  default `Codable` encodes `Date` as seconds since 2001, so send numbers your struct expects.
- **Budget.** Updates go at priority 5. Only updates with an `alert` use 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](/docs/troubleshooting#read-the-timeline).

Something not arriving? Start with [Troubleshooting](/docs/troubleshooting).
