Skip to main content
PUT
/
live-activity
/
stream
/
{stream_key}
Node
import ActivitySmith from "activitysmith";

const activitysmith = new ActivitySmith({
  apiKey: process.env.ACTIVITYSMITH_API_KEY,
});

await activitysmith.liveActivities.stream("search-reindex", {
  content_state: {
    title: "Search Reindex",
    subtitle: "catalog-v2",
    type: "progress",
    percentage: 42,
  },
});
{
  "success": true,
  "operation": "started",
  "stream_key": "prod-web-1",
  "activity_id": "h8QmSyYFTuwOIF6Wh3YcZlzHLhUcr034",
  "devices_notified": 2,
  "timestamp": "2025-08-12T12:00:00.000Z"
}
Use this endpoint when you want ActivitySmith to manage the Live Activity for you.
  • Send the latest state for a stable stream_key.
  • If the Live Activity does not exist yet, ActivitySmith starts it.
  • If it already exists, ActivitySmith updates it.
  • You do not need to keep local state between updates.
  • For timer, send duration_seconds for countdowns. To start at 00:00 and count up, set counts_down to false and leave out duration_seconds.
  • Later timer updates can change visible fields without sending duration_seconds.
This is a good fit for cron jobs, scheduled tasks, CI workflows, monitoring jobs, and background workers that only know the latest state. To stop a managed stream, use DELETE /live-activity/stream/{stream_key}.

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
stream_key
string
required

Stable identifier for one ongoing thing. Allowed characters: letters, numbers, underscores, and hyphens.

Maximum string length: 255
Pattern: ^[A-Za-z0-9_-]+$

Body

application/json

Send the latest state for a managed Live Activity stream. channels is the streamlined form for stream targeting. target.channels is also accepted for compatibility. If both are provided, they must match.

​
content_state
object
required

Current state for a managed Live Activity stream. Include type on the first PUT, and whenever the stream may need to start a fresh activity. Supports segmented_progress, progress, metrics, stats, alert, and timer types. For timer, send duration_seconds to start or reset a bounded timer; omit duration_seconds on later updates to preserve the existing timer window.

​
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
​
channels
string[]

Channel slugs. When omitted, API key scope determines recipients.

Minimum array length: 1
​
target
object

Response

Stream reconciled

Returned after a managed stream request is reconciled.

​
success
boolean
required
​
operation
enum<string>
required
Available options:
started,
updated,
rotated,
noop,
paused
​
stream_key
string
required
​
timestamp
string<date-time>
required
​
activity_id
string | null
​
previous_activity_id
string
​
devices_notified
integer
​
devices_queued
integer
​
users_notified
integer
​
effective_channel_slugs
string[] | null