API Reference

The Aivi API is intentionally small. You create and configure an activity or a widget once in the app, then drive it from anywhere with a single HTTP request. Anything that can make an HTTPS call can update a Live Activity or a widget. One kind of widget also talks back: presses on a switchboard reach you as events.

Base URL

All requests go to:

https://api.getaivi.app

Activities live under /activities and widgets under /widgets, each addressed by its slug. The earlier singular paths, /activity/{slug} and /widget/{slug}, answer the same way and stay supported, so automations that already use them need no change.

Authentication

Every request must include your API token in the Authorization header, using the Token scheme:

Authorization: Token YOUR_API_TOKEN

You get your token in the app: open the Settings tab, sign in with your Apple account, and subscribe to a plan to unlock API access. The token stays the same until you rotate it.

Caution

API access requires an active subscription. A valid token without an active subscription is rejected with a 402 response. See Errors.

Check your account

GET /account

Returns whether your subscription is active and until when. Unlike every other endpoint, it answers 200 while the subscription is inactive, so you can check a token, and whether the API will answer, in one call.

curl https://api.getaivi.app/account \
  -H "Authorization: Token YOUR_API_TOKEN"

subscription takes one of three shapes, told apart by state:

{ "subscription": { "state": "active", "expires_at": "2026-11-12T09:30:00Z", "renews": true } }
{ "subscription": { "state": "expired", "expired_at": "2026-09-01T12:30:15Z" } }
{ "subscription": { "state": "none" } }

state	Meaning	Fields
active	The API answers.	expires_at: when the paid period ends, or null if it does not end. renews: whether it renews at expires_at.
expired	The subscription ended. Other endpoints answer 402.	expired_at: when it ended, the same date as in the 402 body.
none	The account never had one. Other endpoints answer 402.	None.

Update an activity

PATCH /activities/{slug}

Updates the activity identified by slug and pushes the new state to every subscribed device. This is the only endpoint you need to drive Live Activities.

Note

The activity itself is created in the app, where you pick its template and assign the slug. The API updates an existing activity; it does not create one. Updating an activity that does not exist returns 404.

Path parameters

Parameter	Type	Description
slug	string	The unique ID you gave the activity in the app (e.g. dishwasher).

Request body

The body has two top-level fields: a lifecycle state and a content object that describes what to render.

Field	Type	Description	Required?
state	State	Whether the activity should be live on devices.	Yes
content	Content	The template payload to render.	Yes

Activity states

The state field controls the lifecycle of the Live Activity on every subscribed device. There are two values:

state	What it does
ONGOING	The activity is live. The first ONGOING update starts it; later ones update it in place.
IDLE	The activity is not live. Sending IDLE ends an active Live Activity and dismisses it.

A typical flow sets state to ONGOING while a task is running, then to IDLE once it finishes. How long a finished activity lingers on screen before it disappears is controlled by the per-activity dismissal delay you configure in the app.

Activity content

The content object is chosen by its template field, which decides both the layout and the rest of the fields it accepts. Three templates are available:

template	Use it for
progress	Progress bars: cycles, charging, prints, downloads.
monitor	One or two columns of labeled live values.
generic	The original simple progress layout.	Legacy

Each template’s full field list, example payloads, and rendered previews live on the Live Activity Templates page. Shared building blocks such as colors, icons, value formatters, and the tap action URL are documented there too.

Example request

curl https://api.getaivi.app/activities/{slug} \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  --data-binary @- << 'EOF'
{
  "state": "ONGOING",
  "content": {
    "template": "progress",
    "icon": "washer",
    "progress": { "style": "simple", "value": 0.35 },
    "header_left": { "value": "In progress", "text_color": "green" },
    "header_right": { "value": "35 min" }
  }
}
EOF

Response

A successful update returns 200 OK and echoes the stored state and content:

{
  "state": "ONGOING",
  "content": {
    "template": "progress",
    "icon": "washer",
    "progress": { "style": "simple", "value": 0.35 },
    "header_left": { "value": "In progress", "text_color": "green" },
    "header_right": { "value": "35 min" }
  }
}

Tip

PATCH is safe to call repeatedly. Aivi only pushes to devices when the content actually changes, so sending the same payload twice does not waste battery or count against update budgets.

Update a widget

PATCH /widgets/{slug}

Updates the persistent widget identified by slug, stores the new content, and notifies every device that displays it. Authentication is the same as for activities.

Note

Like activities, widgets are created in the app, where you pick the template and assign the slug. The API updates an existing widget; updating a widget that does not exist returns 404.

Path parameters

Parameter	Type	Description
slug	string	The unique ID you gave the widget in the app (e.g. living-room).

Request body

Field	Type	Description	Required?
content	Content	The template payload to render.	Yes
stale_after	int | null	Freshness threshold in seconds (60–604800). Content older than this is marked as stale on device. Omit the field to keep the widget’s current setting; send null to clear it.	No

Widgets have no lifecycle state: unlike an activity, a widget is always “on” and simply shows the latest content you sent.

Widget content

The content object is chosen by its template field. Eleven templates are available: Status, Progress, Gauge, Battery, Budget, Trend, Countdown, List, Prices, Energy, and Switchboard. Each update replaces the previous content as a whole; there is no partial merge.

Every template’s schema, example payload, and rendered previews live on the Widget Templates page. Widget templates share the same building blocks as the activity templates: colors, icons, value formatters, and tap action URLs.

Example request

curl https://api.getaivi.app/widgets/{slug} \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  --data-binary @- << 'EOF'
{
  "content": {
    "template": "gauge",
    "value": 21.5,
    "min_value": 0,
    "max_value": 40,
    "unit": "°C",
    "label": "Living room",
    "icon": "thermometer.medium"
  },
  "stale_after": 3600
}
EOF

Response

A successful update returns 200 OK and echoes the stored content along with the widget’s effective stale_after, including when the request left stale_after out to keep the existing setting:

{
  "content": {
    "template": "gauge",
    "value": 21.5,
    "min_value": 0,
    "max_value": 40,
    "unit": "°C",
    "label": "Living room",
    "icon": "thermometer.medium"
  },
  "stale_after": 3600
}

Note

Widget pushes are delivered at background priority: iOS batches and budgets them, so a change typically appears on device within minutes, not seconds. See the freshness model for what stays live between pushes.

Receive events

Presses on an interactive widget, such as a switchboard, come back to you as widget.action.v1 events. Receiving Events documents the event envelope and both ways to receive it:

Request	Description
GET /events	A server-sent event stream of your account’s events, filterable by type and subject.
PUT /widgets/{slug}/webhooks	Sets the widget’s webhooks: one per action id, and "*" for the rest.
GET /widgets/{slug}/webhooks	Returns the widget’s webhooks, redacted, with the time of each one’s last success and failure.
DELETE /widgets/{slug}/webhooks	Removes the widget’s webhooks.

To confirm what a press did, publish the widget’s new content with PATCH /widgets/{slug}.

Errors

Errors use standard HTTP status codes and return a JSON body with a detail field describing what went wrong.

Status	detail	Cause
400	Template mismatch	The content.template does not match the template the activity or widget was created with.
401	Could not validate credentials	The Authorization header is missing, malformed, or the token is unknown.
402	No active subscription was found	The token is valid but the account has no active subscription.
404	Activity not found	No activity with that slug exists on your account.
404	Widget not found	No widget with that slug exists on your account.
422	Too many ongoing activities	Starting this activity would exceed your concurrent-activity quota.
422	Invalid widget content	The widget content fails its template schema.
422	Content exceeds the 4 KiB limit	The widget content is larger than 4 KiB as compact JSON.
422	array of field errors	The request body is missing fields or has invalid values.
422	array of field errors	The activity content (with its name) would make a Live Activity push larger than Apple’s 4096-byte limit: type payload_too_large at content, with ctx.size and ctx.limit in bytes.
429	Too many event streams	Your account already has 4 /events streams open.

Note

The validation 422 is the one exception to the detail shape above: its detail is an array of field-level error objects (loc, msg, type) rather than a string.

Note

Live Activities are also subject to system budgets enforced by iOS, separate from these API errors. See Limitations for the details.

OpenAPI specification

A machine-readable OpenAPI document is generated from the API itself and served at https://api.getaivi.app/openapi.json. Import it into an OpenAPI-compatible client such as Postman or Insomnia to explore the schema and make test requests.