POST /api/start

Create an activity and get its launch button. The card appears when a phone opens the button.

Send the key as the x-api-key header on every call. All requests are Content-Type: application/json, and field names are exact camelCase (accentColorHex, never accent_color_hex). Errors are listed in errors and limits.

Body

Field	Type	Instructions
`state`	object	Required. What the card shows. See layouts and the state object.
`widgetContainerId`	string	Required. Any text that names the widget, for example "pizza-tracker". Send the same value on every later call for this widget. A phone keeps one activity per container.
`group`	string	A label, so one call can update or end many activities.
`brand`	object	The activity's name and branding. See the brand object.
`reuse`	boolean	`true` lets one launch button serve many phones. See one button, many phones.
`keepAlive`	boolean	`true` restarts the card every 7 hours, before iOS ends it. Each restart alerts. Use it for a countdown or anything else that runs longer than 8 hours. See long-running activities.
`webhookIdentifier`	string	Sends this activity's webhook events to the endpoint with this identifier. See webhooks.

Basic start

The simplest start: a progress bar with a headline and a logo.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "acme-orders",
  "brand": {
    "title": "Order #1234"
  },
  "state": {
    "layout": "progress",
    "primaryText": "Order received",
    "progress": 0.1,
    "accentColorHex": "#0A84FF",
    "headerIconUrl": "https://acme.example/logo.png"
  }
}'

Start with every option

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "acme-orders",
  "group": "order-tracker",
  "keepAlive": true,
  "webhookIdentifier": "staging",
  "brand": {
    "title": "Order #1234",
    "name": "Acme",
    "logo": "https://acme.example/logo.png",
    "description": "Track your Acme order from kitchen to door",
    "color": "#06C167"
  },
  "state": {
    "layout": "progress",
    "primaryText": "Order received",
    "secondaryText": "We will start soon",
    "progress": 0.1
  }
}'

Response

Answers 201. Keep the activityId for updates and ends. userId is the same id, under the name the phone apps use. group is empty when none was sent.

{
  "ok": true,
  "activityId": "act-8f2cqa4mx7rd",
  "userId": "act-8f2cqa4mx7rd",
  "group": "order-tracker",
  "widgetContainerId": "acme-orders",
  "links": {
    "iframe": "<iframe src=\"https://api.webliveactivity.com/embed/button?type=track&userId=act-8f2cqa4mx7rd\" width=\"340\" height=\"95\" style=\"border:0;color-scheme:light\"></iframe>"
  }
}

The launch button

Put links.iframe on a web page. On a phone, a tap opens the activity. On a computer, a click shows a QR code to scan with the phone.

The iframe's src takes three optional settings:

Setting	Values	Instructions
`color`	A 6-digit hex color, without `#`	The button's color. Example: `&color=06C167`. A light color gets dark text. Default: the `type`'s color.
`theme`	`light` (default), `dark`	The color of the "Powered By" text under the button. On a dark page, add `&theme=dark` and change `color-scheme:light` to `color-scheme:dark` in the iframe's `style`.
`type`	`track` (default), `launch`, `add`	The button's icon, label, and default color. Push groups use `notify`, `subscribe`, or `follow`.

The background is transparent. Only the color can change: the icon and label come from type, and a "Powered By" line shows under the button on every plan.

The page that hosts the button becomes the site shown with the activity on the phone. The API cannot set it. The button does not load on a page that hides its referrer (Referrer-Policy: no-referrer or same-origin, or referrerpolicy="no-referrer" on the iframe).