Skip to main content
POST
/
live-activity
/
start
Node
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;
{
  "success": true,
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "devices_notified": 2,
  "users_notified": 1,
  "timestamp": "2026-01-28T09:57:22.929Z"
}
Use this manual lifecycle endpoint only when you need direct control over a specific Live Activity instance. For new integrations, prefer PUT /live-activity/stream/{stream_key}. This endpoint creates a new Live Activity and returns an activity_id. You will use that same ID for later update and end calls.
  • metrics: send title, type, and a non-empty metrics array.
  • stats: send title, type, and a non-empty metrics array for up to 8 labeled values.
  • segmented_progress: send title, type, number_of_steps, and current_step.
  • progress: send title, type, and either percentage or value with upper_limit.
  • timer: send title, type, and duration_seconds for a countdown. To start at 00:00 and count up, set counts_down to false and leave out duration_seconds.
  • action is optional if you want the Live Activity to show one button that opens a URL or triggers a webhook.
  • target.channels is optional if you want to scope delivery to specific channel slugs.
For segmented_progress, number_of_steps is not fixed for the full lifecycle. You can change it later in update or end calls if the workflow adds or removes steps.

Authorizations

​
Authorization
string
header
required

Required. Include Authorization: Bearer ask_123456789 in every request. Replace ask_123456789 with your API key.

Body

application/json

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

​
content_state
object
required

Start payload requires title and type. For segmented_progress include number_of_steps and current_step. For progress include percentage or value with upper_limit. For metrics and stats include a non-empty metrics array. For alert include message. For timer include duration_seconds for countdowns, or set counts_down false without duration_seconds for an open-ended elapsed timer. Optional icon is supported by all Live Activity types. Optional badge is supported by alert, progress, and segmented_progress. For segmented_progress, number_of_steps is not locked and can be changed in later update or end calls.

​
action
object

Optional action button shown in the Live Activity UI. Use action for the primary button, or secondary_action for a secondary button on alert, progress, and segmented_progress Live Activities.

​
secondary_action
object

Optional secondary action button. Supported only for alert, progress, and segmented_progress Live Activities. Uses the same open_url, shortcuts://, and webhook shapes as action.

​
alert
object
​
target
object

Response

Live Activity started

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

​
success
boolean
required
​
activity_id
string
required
​
timestamp
string<date-time>
required
​
devices_notified
integer
​
users_notified
integer
​
effective_channel_slugs
string[] | null