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.

Base URL

All requests go to:

https://api.getaivi.app

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.

Update an activity

PATCH /activity/{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/activity/{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 /widget/{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. Ten templates are available: Status, Progress, Gauge, Battery, Budget, Trend, Countdown, List, Prices, and Energy. 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/widget/{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.

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 or exceeds the 4 KiB limit.
422	array of field errors	The request body is missing fields or has invalid values.

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.