# API

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

Updated 2026-11-21

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](https://liveactivity.dev/api/v1/openapi.json) is
available without a key.

## Authentication

Create a secret key in **Settings → Organization → API keys** and send it as a bearer token:

```sh
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](/docs/troubleshooting).

## The activity object

```json
{
  "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.

```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" }
  }'
```

## 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`. |

```sh
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).

```json
{
  "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](/docs/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.

```sh
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.

```sh
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.

```sh
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.

```json
{
  "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.

```sh
curl https://liveactivity.dev/api/v1/apps -H "Authorization: Bearer $API_KEY"
```
