POST /api/start

Begin a Live Activity for one user and return the handle and its launch links.

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

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 a group

A group lets you update or end every activity in the group at once. Set keepAlive for trackers that run longer than ~8 hours.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "group": "order-tracker",
  "widgetContainerId": "acme-orders",
  "keepAlive": true,
  "brand": {
    "title": "Order #1234"
  },
  "state": {
    "layout": "progress",
    "primaryText": "Order received",
    "progress": 0.1
  }
}'

Start with branding

Add a full brand to name the activity (title) and set the cover the user sees when they first open it. The brand name, logo, and color flow through the whole experience.

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",
    "name": "Acme",
    "url": "https://acme.example",
    "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,
    "stage": "Received"
  }
}'

Start with a webhook

Route lifecycle events to a specific endpoint by its identifier. See webhooks for the full contract.

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",
  "webhookIdentifier": "staging",
  "brand": {
    "title": "Order #1234"
  },
  "state": {
    "layout": "progress",
    "primaryText": "Order received",
    "progress": 0.1
  }
}'

Response

Returns { ok, activityId, group, widgetContainerId, links }. Keep the activityId to target updates and ends. Surface one of the links (iframe, redirect, qr) to let users join.

The iframe renders on a transparent background and takes two optional query parameters for placement: theme (light, the default, or dark) sets the information text under the button to read on your surface, and type (track, launch, add for an activity; notify, subscribe, follow for a push group) picks its icon and label. Neither the visitor's system setting nor theme changes the button itself. Match the color-scheme in the iframe's style to theme (light by default, dark alongside theme=dark): that pairing keeps the background transparent whatever colour scheme your own page declares.

{
  "ok": true,
  "activityId": "act-8f2c1a",
  "group": "order-tracker",
  "widgetContainerId": "acme-orders",
  "links": {
    "iframe": "<iframe src=\"https://api.example.com/embed/button?type=track&userId=act-8f2c1a\" ...></iframe>",
    "redirect": "https://webliveactivity.com/clip/act-8f2c1a",
    "qr": "https://api.example.com/embed/qr?type=track&userId=act-8f2c1a"
  }
}

Layout examples

Segmented steps

Discrete stages instead of a continuous bar. Each step flips to complete as the tracker advances.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "pizza-tracker",
  "brand": {
    "title": "Order #1234"
  },
  "state": {
    "layout": "progress",
    "primaryText": "In the oven now",
    "secondaryText": "Your order is being cooked",
    "accentColorHex": "#0A84FF",
    "backgroundColorHex": "#0080BA",
    "headerIconUrl": "https://acme.example/logo.png",
    "estimatedMinutes": 30,
    "progressStyle": "segmented",
    "segments": [
      {
        "label": "Cooking",
        "complete": false
      },
      {
        "label": "On the way",
        "complete": false
      },
      {
        "label": "Delivered",
        "complete": false
      }
    ]
  }
}'

Picture card

A photo-forward layout where the image is the focus. Good for pet matches, listings, camera feeds.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "pet-matches",
  "brand": {
    "title": "Meet Luna"
  },
  "state": {
    "layout": "picture",
    "primaryText": "Luna",
    "secondaryText": "2 year old Tabby, Spayed",
    "accessoryText": "New match",
    "accentColorHex": "#FF6B35",
    "headerIconUrl": "https://petfinder.example/luna.jpg",
    "actionLabel": "View Live",
    "actionURL": "https://petfinder.example/luna"
  }
}'

Versus matchup

Two sides with scores, logos, statuses, and a center column. Good for sports, esports, live auctions.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "csgo-scores",
  "brand": {
    "title": "CSGO Esports"
  },
  "state": {
    "layout": "versus",
    "primaryText": "CSGO Esports",
    "accentColorHex": "#0A84FF",
    "backgroundColorHex": "#001226",
    "backgroundGradientHex": "#00428C",
    "actionLabel": "Watch Live",
    "actionURL": "https://hltv.org/matches",
    "versus": {
      "leftName": "Movistar Riders",
      "rightName": "Heroic",
      "leftScore": "9",
      "rightScore": "12",
      "leftStatus": "Terrorist",
      "rightStatus": "Counter Terrorist",
      "activeSide": "right",
      "leftImageUrl": "https://hltv.org/movistar.png",
      "rightImageUrl": "https://hltv.org/heroic.png",
      "centerLabel": "Map",
      "centerValue": "Overpass",
      "sourceLogoUrl": "https://hltv.org/csgo.png"
    }
  }
}'

Countdown

A clock that ticks down on the device toward a target moment. Set it once; the device keeps time.

At the target the service sends a high-priority update on its own: on iOS the Dynamic Island expands and the phone vibrates, on Android the notification alerts. Set completionText to control the words on the card and in that alert; without it the card falls back to secondaryText.

curl -X POST https://api.webliveactivity.com/api/start \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: wla_your_key' \
  -d '{
  "widgetContainerId": "gta6-countdown",
  "brand": {
    "title": "GTA VI"
  },
  "state": {
    "layout": "countdown",
    "primaryText": "Grand Theft Auto VI",
    "secondaryText": "GTA VI",
    "countdownTo": 1763510400,
    "countdownStyle": "days",
    "completionText": "Out now",
    "headerIconUrl": "https://rockstargames.com/gta6-logo.png",
    "backgroundImageUrl": "https://rockstargames.com/gta6-art.jpg"
  }
}'