Skip to main content
PUT
Node
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 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
tags
string[]

Optional tags to organize and filter notification history. Omit this field on later updates to keep the current tags, send tags again to replace them, or send an empty array to clear them.

Required string length: 1 - 64
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Example:

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
tags
string[]

Optional tags to organize and filter notification history.

Required string length: 1 - 64
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Example: