Update Live Activity

Legacy manual lifecycle endpoint. For new integrations, use PUT /live-activity/stream/{stream_key} so ActivitySmith can manage start, update, rotation, and end state for you. This endpoint remains supported for existing integrations and advanced lifecycle control. Updates an existing Live Activity. If the per-activity token is not registered yet, the update is queued. Supports segmented_progress, progress, metrics, stats, alert, timer, and value activity types. For segmented_progress activities, you can increase or decrease number_of_steps here as the workflow changes. For timer activities, send duration_seconds only when you want to reset the timer window; omit it to keep the current timer running. Use secondary_action for a second button on alert, progress, segmented_progress, and value Live Activities.

POST https://activitysmith.com/api/live-activity/update

Authentication#

Use your API key in the request header.

Authorization: Bearer $YOUR_API_KEY

Request examples#

import ActivitySmith from "activitysmith";
const activitysmith = new ActivitySmith({
  apiKey: process.env.ACTIVITYSMITH_API_KEY,
});
await activitysmith.liveActivities.update({
  activity_id: "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  content_state: {
    title: "Nightly database backup",
    subtitle: "upload archive",
    number_of_steps: 3,
    current_step: 2,
  },
});

Bodyapplication/json

Update an existing Live Activity by activity_id.

metadataMetadata

activity_idstringrequired

tagsarray of string

Tags for notification history. Omit to keep existing Tags, supply an array to replace them, or send an empty array to clear them.

Max Items: 20 Item constraints:

Min Length: 1

Max Length: 64

content_stateContentStateUpdaterequired

actionLiveActivityAction

secondary_actionLiveActivityAction

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

Additional Properties: false

segmented progress

{
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "content_state": {
    "title": "Nightly database backup",
    "subtitle": "upload archive",
    "number_of_steps": 3,
    "current_step": 2
  }
}

progress

{
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "content_state": {
    "title": "EV Charging",
    "subtitle": "Added 120 mi range",
    "percentage": 60
  }
}

metrics

{
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "content_state": {
    "title": "Server Health",
    "subtitle": "prod-web-1",
    "type": "metrics",
    "metrics": [
      {
        "label": "CPU",
        "value": 25,
        "unit": "%"
      },
      {
        "label": "MEM",
        "value": 67,
        "unit": "%"
      }
    ]
  }
}

webhook action

{
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "content_state": {
    "title": "Reindexing product search",
    "subtitle": "Shard 7 of 12",
    "number_of_steps": 12,
    "current_step": 7
  },
  "action": {
    "title": "Pause Reindex",
    "type": "webhook",
    "url": "https://ops.example.com/hooks/search/reindex/pause",
    "method": "POST",
    "body": {
      "job_id": "reindex-2026-03-19",
      "requested_by": "activitysmith_live_activity",
      "reason": "paused_from_ios_live_activity"
    }
  }
}

timer preserve window

{
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "content_state": {
    "title": "Benchmark Run",
    "subtitle": "checking p95 latency",
    "type": "timer"
  }
}

timer reset window

{
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "content_state": {
    "title": "Benchmark Run",
    "subtitle": "retrying sample",
    "type": "timer",
    "duration_seconds": 180
  }
}

Responses#

200#

Live Activity updated (or queued)

Content type: application/json

Schema: LiveActivityUpdateResponse#

Returned after a Live Activity update is sent or queued.

successbooleanrequired

activity_idstringrequired

devices_queuedinteger

devices_notifiedinteger

timestampstring<date-time>required

Additional Properties: false

sent

{
  "success": true,
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "devices_notified": 2,
  "devices_queued": 0,
  "timestamp": "2026-01-28T09:57:26.056Z"
}

403#

Forbidden (activity not owned by this API key account)

Content type: application/json

Schema: ForbiddenError#

errorstringrequired

messagestringrequired

Additional Properties: true

forbidden

{
  "error": "Forbidden",
  "message": "This API key cannot update this Live Activity"
}

429#

Rate limit exceeded

Content type: application/json

Schema: RateLimitError#

codestring

Enum: ["rate_limited"]

errorstringrequired

messagestringrequired

Additional Properties: false

rate limited

{
  "error": "Rate limit exceeded",
  "message": "Too many requests, please try again later."
}

Download the OpenAPI specification