Skip to main content
POST
/
live-activity
/
start
curl --request POST \
  --url https://activitysmith.com/api/live-activity/start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content_state": {
    "title": "Nightly database backup",
    "subtitle": "create snapshot",
    "number_of_steps": 3,
    "current_step": 1,
    "type": "segmented_progress",
    "color": "yellow"
  }
}
'
{
  "success": true,
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "devices_notified": 2,
  "users_notified": 1,
  "timestamp": "2026-01-28T09:57:22.929Z"
}
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.
  • 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 include a non-empty metrics array. Legacy counter/timer/countdown types also use current_step and number_of_steps. 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