Live Activities EndpointsView Markdown ↗

Start Live Activity

Start a Live Activity (legacy manual lifecycle)

Legacy manual lifecycle endpoint. For new integrations, use PUT /live-activity/stream/{stream_key} so ActivitySmith can manage start, update, rotation, and end state for you. This endpoint remains supported for existing integrations and advanced lifecycle control. Starts a Live Activity on devices matched by API key scope and optional target channels. Supports segmented_progress, progress, metrics, stats, alert, timer, and value activity types. For segmented_progress activities, number_of_steps can be changed later during update or end calls if the workflow changes. Use secondary_action for a second button on alert, progress, segmented_progress, and value Live Activities. Optional tags to organize and filter notification history.

POST https://activitysmith.com/api/live-activity/start

Authentication#

Use your API key in the request header.

Authorization: Bearer $YOUR_API_KEY

Request examples#

import ActivitySmith from "activitysmith";
const activitysmith = new ActivitySmith({
  apiKey: process.env.ACTIVITYSMITH_API_KEY,
});
const start = await activitysmith.liveActivities.start({
  content_state: {
    title: "Nightly database backup",
    subtitle: "create snapshot",
    number_of_steps: 3,
    current_step: 1,
    type: "segmented_progress",
    color: "yellow",
  },
});
const activityId = start.activity_id;

Bodyapplication/json

Start a new Live Activity. The response includes activity_id for later update and end calls.

metadataMetadata
content_stateContentStateStartrequired
actionLiveActivityAction
secondary_actionLiveActivityAction: Optional secondary action button. Supported for alert, progress, segmented_progress, and value Live Activities. Uses the same open_url, shortcuts://, and webhook shapes as action.
alertAlertPayload
targetChannelTarget
tagsTagSlugs

Additional Properties: false

segmented progress

{
  "content_state": {
    "title": "Nightly database backup",
    "subtitle": "create snapshot",
    "number_of_steps": 3,
    "current_step": 1,
    "type": "segmented_progress",
    "color": "yellow"
  }
}

progress

{
  "content_state": {
    "title": "EV Charging",
    "subtitle": "Added 30 mi range",
    "percentage": 15,
    "type": "progress",
    "color": "lime"
  }
}

metrics

{
  "content_state": {
    "title": "Server Health",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      {
        "label": "CPU",
        "value": 21,
        "unit": "%"
      },
      {
        "label": "MEM",
        "value": 64,
        "unit": "%"
      }
    ]
  }
}

open url action

{
  "content_state": {
    "title": "Deploying payments-api",
    "subtitle": "Running database migrations",
    "number_of_steps": 5,
    "current_step": 3,
    "type": "segmented_progress"
  },
  "action": {
    "title": "Open Workflow",
    "type": "open_url",
    "url": "https://github.com/acme/payments-api/actions/runs/1234567890"
  }
}

segmented progress channel targeted

{
  "content_state": {
    "title": "Nightly database backup",
    "subtitle": "create snapshot",
    "number_of_steps": 3,
    "current_step": 1,
    "type": "segmented_progress",
    "color": "yellow"
  },
  "target": {
    "channels": [
      "devs",
      "ops"
    ]
  }
}

Current revenue with a badge and footer button

{
  "content_state": {
    "type": "value",
    "title": "Current revenue",
    "subtitle": "Today",
    "value": "$1,240",
    "color": "cyan",
    "icon": "dollarsign.circle",
    "badge": {
      "title": "Live",
      "color": "green"
    }
  },
  "action": {
    "title": "Dashboard",
    "type": "open_url",
    "url": "https://example.com/dashboard"
  }
}

timer

{
  "content_state": {
    "title": "Benchmark Run",
    "subtitle": "sampling",
    "type": "timer",
    "duration_seconds": 300,
    "color": "cyan"
  }
}

approval secondary actions

{
  "content_state": {
    "title": "Approval Needed",
    "message": "Should I send the follow-up email to Brightlane?",
    "type": "alert",
    "color": "cyan"
  },
  "action": {
    "title": "Send",
    "type": "webhook",
    "url": "https://example.com/hooks/approvals/send",
    "method": "POST",
    "body": {
      "approval_id": "appr_123"
    }
  },
  "secondary_action": {
    "title": "Deny",
    "type": "webhook",
    "url": "https://example.com/hooks/approvals/deny",
    "method": "POST",
    "body": {
      "approval_id": "appr_123"
    }
  }
}

Organize notification history with tags

{
  "content_state": {
    "title": "Nightly database backup",
    "subtitle": "create snapshot",
    "number_of_steps": 3,
    "current_step": 1,
    "type": "segmented_progress",
    "color": "yellow"
  },
  "tags": [
    "user:382",
    "database-backup"
  ]
}

Responses#

200#

Live Activity started

Content type: application/json

Schema: LiveActivityStartResponse#

Returned after a Live Activity starts. Save activity_id and use it for all later updates and for the final end call.

successbooleanrequired
devices_notifiedinteger
users_notifiedinteger
activity_idstringrequired
effective_channel_slugsarray of string or null
tagsTagSlugs
timestampstring<date-time>required

Additional Properties: false

segmented progress

{
  "success": true,
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "devices_notified": 2,
  "users_notified": 1,
  "timestamp": "2026-01-28T09:57:22.929Z"
}

segmented progress channel targeted

{
  "success": true,
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "devices_notified": 2,
  "users_notified": 1,
  "effective_channel_slugs": [
    "devs",
    "ops"
  ],
  "timestamp": "2026-01-28T09:57:22.929Z"
}

tagged

{
  "success": true,
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "devices_notified": 2,
  "users_notified": 1,
  "tags": [
    "user:382",
    "database-backup"
  ],
  "timestamp": "2026-01-28T09:57:22.929Z"
}

400#

Bad request (invalid payload or channel targeting input)

Content type: application/json

Schema: BadRequestError#

errorstringrequired
messagestringrequired

Additional Properties: true

invalid target

{
  "error": "Invalid channel targeting",
  "message": "target.channels must be an array of channel slugs"
}

invalid tags

{
  "error": "Invalid tags",
  "code": "invalid_tags",
  "message": "tags must use 1-64 lowercase letters, numbers, dashes, underscores, periods, or colons"
}

402#

Billing access required

Content type: application/json

Schema: BillingBlockedError#

errorstringrequired: Enum: ["trial_expired","trial_exhausted","billing_overage_cap_reached"]
messagestringrequired
trial_periodobject
trial_period.started_atstring<date-time>required
trial_period.ends_atstring<date-time>required
upgrade_urlstring<uri>required

Additional Properties: true

403#

Forbidden (API key scope or channel assignment violation)

Content type: application/json

Schema: ForbiddenError#

errorstringrequired
messagestringrequired

Additional Properties: true

channel scope violation

{
  "error": "Invalid channel targeting",
  "message": "This API key can only target assigned channels. Requested channels include channels outside this key scope."
}

422#

No recipients found for effective channel target

Content type: application/json

Schema: NoRecipientsError#

errorstringrequired
messagestringrequired
effective_channel_slugsarray of string or null

Additional Properties: true

no devices

{
  "error": "No recipients found",
  "message": "No Live Activity devices matched the effective channel target",
  "effective_channel_slugs": [
    "marketing"
  ]
}

429#

Rate limit exceeded

Content type: application/json

oneOf

Schema: RateLimitError

Schema: LiveActivityLimitError

rate limited

{
  "error": "Rate limit exceeded",
  "message": "Too many requests, please try again later."
}

concurrent live activity limit reached

{
  "error": "Live Activity limit reached",
  "message": "iOS supports up to 5 concurrent Live Activities per app on a device. End an active Live Activity before starting another.",
  "limit": 5,
  "active": 5
}

Download the OpenAPI specification