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" }

Documentation Index

Fetch the complete documentation index at: https://activitysmith.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Use this endpoint to create a new Live Activity and get back 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.
  • 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 segmented_progress, number_of_steps is not locked and can be changed in later update or end calls.

​
action
object

Optional single action button shown in the Live Activity UI.

​
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