Base URL: https://liveactivity.dev/api/v1. Bodies and responses are JSON. All times are integers in
milliseconds since the Unix epoch. An OpenAPI description is
available without a key.
Authentication
Create a secret key in Settings → Organization → API keys and send it as a bearer token:
curl https://liveactivity.dev/api/v1/apps -H "Authorization: Bearer $API_KEY"
Keys start with sk_, belong to the organization, and must stay on your server. The pk_ key you ship in your app
does not work here. Session cookies are not accepted either.
Rate limit. 300 requests a minute per key. Above that you get 429 with Retry-After: 60.
Errors
Errors are JSON, { "error": "message" }, sometimes with details:
| Status | Meaning |
|---|---|
| 400 | The body isn’t valid JSON. |
| 401 | Missing or invalid key. |
| 402 | The plan’s limit is reached (apps, or Live Activities started this month), or the feature isn’t on your plan. |
| 404 | App or activity not found. |
| 409 | The activity is in the wrong state: updating one that has ended, been cancelled or failed, or cancelling one that has started. |
| 422 | Invalid input, or the content state doesn’t fit. |
| 429 | Rate limited. |
422 and the content state
We check contentState before queueing a push, because iOS drops a push whose content state it can’t decode, and says
nothing. A 422 means one of:
- the body doesn’t match the schema (
detailsis the list of problems), contentStatehas a key the app’sContentStatedoesn’t have, or a value of another JSON type than the app sends (erroriscontentState doesn't match DeliveryAttributes.ContentState: …,detailslists every difference),- the push would be over APNs’ 4096 bytes.
The shape comes from what the SDK last reported for that attributesType. Keys the app never sent may be missing, and
null is accepted anywhere. See Troubleshooting.
The activity object
{
"id": "act_8f2c61d0b7a94e3f9a1c2d3e4f5a6b7c",
"appId": "3f0c9a52-6d1e-4b7a-8c25-0e9d4f1a7b36",
"userId": "user_42",
"installId": null,
"attributesType": "DeliveryAttributes",
"attributes": { "orderId": "1234" },
"contentState": { "eta": 15, "status": "cooking" },
"status": "scheduled",
"startAt": 1795180000000,
"staleDate": null,
"endedAt": null,
"version": 0,
"createdAt": 1795179990000
}
status is scheduled, starting, active, ended, cancelled or failed. version goes up on every update and
end.
Start an activity
POST /activities returns 201 with the activity (status: "scheduled").
| Field | Type | |
|---|---|---|
appId |
string | Required. The App ID from the dashboard. |
attributesType |
string | Required. The Swift ActivityAttributes type name, e.g. DeliveryAttributes. |
contentState |
object | Required. Must match the app’s ContentState. |
attributes |
object | The static attributes. Default {}. We add lacId ourselves. |
userId |
string | The ID passed to identify in the app. One of userId or installId is required. Up to 128 characters. |
installId |
string | Target one install instead of all of a user’s devices. |
startAt |
integer | When to start. Leave out to start now. A time in the past starts now. |
alert |
object | { title, body, sound? }. What the user sees when the activity appears. Defaults to empty strings. |
staleDate |
integer | When iOS marks the activity stale. |
We push-to-start at startAt to every install of the user that has a push-to-start token for attributesType. If
there is none, the activity becomes failed and you get a delivery.failed webhook. Starting counts against your
plan’s Live Activities a month.
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" }
}'
List activities
GET /activities returns { "activities": [ … ] }, the latest 100, newest first.
| Query | |
|---|---|
appId |
Only this app. |
status |
One or more statuses, comma separated, e.g. active,starting. |
q |
An activity ID, or the beginning of a userId or installId. |
curl "https://liveactivity.dev/api/v1/activities?appId=<app id>&status=active" -H "Authorization: Bearer $API_KEY"
Get an activity
GET /activities/:id returns the activity plus targets (one per device) and events (the timeline, newest first,
up to 200).
{
"id": "act_8f2c61d0b7a94e3f9a1c2d3e4f5a6b7c",
"status": "active",
"…": "…",
"targets": [
{ "installId": "6B1F…", "activityKitId": "A1B2…", "status": "active", "hasPushToken": true, "sentVersion": 2, "updatedAt": 1795180004000 }
],
"events": [
{ "id": "…", "type": "apns.update", "installId": "6B1F…", "detail": { "version": 2, "status": 200, "apnsId": "…" }, "createdAt": 1795180004000 }
]
}
A target’s status is pending, sent, active, stale, ended, dismissed or failed. Event types are listed
in Troubleshooting.
Update an activity
PATCH /activities/:id with contentState (required) and optionally alert, staleDate and relevanceScore.
It returns the activity. The new state goes to every device that has the activity. Send the whole content state, not a
patch. Rapid updates collapse into the newest.
An update with alert is sent at APNs priority 10, which counts against Apple’s hourly budget. Without alert it is
priority 5. An activity that hasn’t started yet just stores the new state, which the start push then carries.
curl -X PATCH https://liveactivity.dev/api/v1/activities/act_… \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{ "contentState": { "eta": 5, "status": "on the way" } }'
End an activity
POST /activities/:id/end with optional contentState (the final state) and dismissalDate (when iOS removes it
from the lock screen). It returns the activity with status: "ended". Ending an activity that is still scheduled
cancels it. Ending one that is already finished changes nothing.
curl -X POST https://liveactivity.dev/api/v1/activities/act_…/end \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{ "contentState": { "eta": 0, "status": "delivered" } }'
Cancel a scheduled start
DELETE /activities/:id returns the activity with status: "cancelled". Only a scheduled activity can be
cancelled, anything else is 409: end it instead. A start the app scheduled on the device (iOS 26) stays scheduled
there.
curl -X DELETE https://liveactivity.dev/api/v1/activities/act_… -H "Authorization: Bearer $API_KEY"
List apps
GET /apps returns { "apps": [ … ] }, the apps of your organization.
{
"apps": [
{
"id": "3f0c9a52-6d1e-4b7a-8c25-0e9d4f1a7b36",
"orgId": "c1d2e3f4-0000-4000-8000-000000000000",
"name": "Delivery",
"bundleId": "com.example.delivery",
"teamId": "ABCDE12345",
"keyId": "FGHIJ67890",
"environment": "sandbox",
"publishableKey": "pk_…",
"webhookUrl": "https://api.example.com/hooks/live-activity",
"webhookSecret": "whsec_…",
"createdAt": "2026-11-21T10:00:00.000Z",
"updatedAt": "2026-11-21T10:00:00.000Z"
}
]
}
The APNs key is never returned. Apps are created and edited in the dashboard.
curl https://liveactivity.dev/api/v1/apps -H "Authorization: Bearer $API_KEY"