API Reference

The Aivi API is intentionally small. You create and configure an activity 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.

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 Account 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.

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

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.

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.

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 Templates page. Shared building blocks such as colors, icons, value formatters, and the tap action URL are documented there too.

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 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.
422	Too many ongoing activities	Starting this activity would exceed your concurrent-activity quota.
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.