Skip to main content

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.

ActivitySmith Live ActivitiesActivitySmith Push Notifications

​
Welcome to ActivitySmith

ActivitySmith is API service that lets you trigger and update Live Activities and send push notifications directly from your own infrastructure. Pair your iOS device(s), authenticate with an API key, and send real-time alerts from any backend, cron, agent, or automation. Without building or maintaining your own iOS app or dealing directly with APNs. Check out the following resources to get started: Want an SDK or Integration? Let us know at adam@activitysmith.com.

​
Prerequisites

​
Features

  • Push Notifications: send push notifications to all paired devices or target specific channels.
  • Live Activities: start, update and end a Live Activity on your lock screen or dynamic island, with optional channel targeting and one optional action button.
  • Widgets: display any value on your Lock Screen with widgets - SaaS metrics, revenue, signups, uptime, habits, or anything else you want to track.
  • Inbound Webhooks: forward events from external services such as Vercel, Netlify, Railway, and more, into Push Notifications and Live Activities.

​
Powerful Capabilities

  • Glanceable observability: monitor real-time system state and long-running operations directly on your lock screen or dynamic island.
  • The hard stuff: APNs(Apple Push Notification service), certificates, orchestration
  • Customizability: adapt the experience to fit your unique needs.
  • Works with any backend: use with any backend, cron, agent, automation or AI tool.
  • iOS app: ready to use native iOS app for your iPhone or iPad. No need to build your own.

​
Push Notifications

To send a push notification, use the push-notification endpoint. It takes title and optional fields like message, payload, media, redirection, actions, and target.channels.
target.channels accepts channel slugs (for example ["devs", "ops"]).
  • media attaches an image, audio file, or video that users can preview or play when they expand the notification.
  • redirection opens on normal tap.
  • actions (up to 4) appear when users expand the notification.
  • media + redirection is supported.
  • media + actions is not supported in v1.
Push Notification 
curl -X POST https://activitysmith.com/api/push-notification \
  -H "Authorization: Bearer $ACTIVITYSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New subscription 💸",
    "message": "Customer upgraded to Pro plan"
  }'
Response 
{
  "success": true,
  "devices_notified": 3,
  "users_notified": 1,
  "timestamp": "2025-08-12T12:00:00.000Z"
}

​
Live Activities

There are four types of Live Activities:
TypeBest forRequired state
statsup to 8 labeled valuestitle, type, and a non-empty metrics array
metricsLive operational statstitle, type, and a non-empty metrics array
segmented_progressJobs tracked in stepstitle, type, number_of_steps, current_step
progressJobs with continuous progresstitle, type, and either percentage or value + upper_limit
Stats Live Activity Metrics Live Activity update Progress Live Activity start Segmented Progress Live Activity update

​
Start & Update Live Activity

Use stream updates to start, update, and dismiss Live Activities with a stable stream_key. Send the latest state for a stable stream_key, and ActivitySmith starts or updates the Live Activity. You do not need to keep local state between updates. When the work is done, call DELETE /live-activity/stream/:stream_key with the same stream_key to dismiss the Live Activity. You can include final values before it is removed. By default, iOS removes the Live Activity after two minutes. Set auto_dismiss_minutes to choose a different dismissal time, including 0 for immediate dismissal.

​
Action Button

Live Activities support one optional action button shown on the Lock Screen. Use it to have a one-tap path from a long-running job to the place where you can act on it. The action field is accepted on stream updates and works with all Live Activity types.
Live Activity with an action button on iPhoneMetrics Live Activity with an action button
There are two action types:
  • open_url: opens the provided HTTPS URL in the browser.
  • webhook: ActivitySmith’s backend calls your HTTPS webhook with GET or POST.
The action object accepts:
FieldRequiredDescription
titleyesButton label shown on the Live Activity.
typeyesEither open_url or webhook.
urlyesHTTPS endpoint to open or call.
methodwebhook onlyGET or POST.
bodywebhook onlyOptional JSON payload sent with the webhook request.

​
open_url

Use open_url when the button should jump the user to a dashboard, run page, or any browser destination tied to the work. 
{
  "content_state": {
    "title": "Deploying payments-api",
    "subtitle": "Running database migrations",
    "number_of_steps": 5,
    "current_step": 3,
    "type": "segmented_progress"
  },
  "action": {
    "title": "Open Workflow",
    "type": "open_url",
    "url": "https://github.com/acme/payments-api/actions/runs/1234567890"
  }
}

​
webhook

Use webhook when the button should trigger an action in your backend, like pausing a job, acknowledging an alert, or canceling a workflow. ActivitySmith calls the URL server-side, so the user does not leave the Lock Screen. 
{
  "content_state": {
    "title": "Reindexing product search",
    "subtitle": "Shard 7 of 12",
    "number_of_steps": 12,
    "current_step": 7,
    "type": "segmented_progress"
  },
  "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"
    }
  }
}
Notes:
  • Only HTTPS URLs are supported for both action types.
  • One button per Live Activity.
  • Pass action on an update call to set or replace the button on an active Live Activity.

​
Channel Targeting

You can scope delivery with channel slugs: 
{
  "target": {
    "channels": ["devs", "ops"]
  }
}
  • If target is omitted and API key scope is all: send to all account recipients.
  • If target is omitted and API key scope is channels: send to channels assigned to that key.
  • If target.channels is present: only those channel slugs are used.