Introducing LiveActivityRead more

Reference / APIMenu

API

REST API reference for starting, updating and ending Live Activities from your backend.

Updated · Markdown · Ask Claude · Ask ChatGPT

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 (details is the list of problems),
  • contentState has a key the app’s ContentState doesn’t have, or a value of another JSON type than the app sends (error is contentState doesn't match DeliveryAttributes.ContentState: …, details lists 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"