Docs / Live ActivitiesMenu

Live Activities

Show a deploy, a backup or a job on the Lock Screen and in the Dynamic Island, and update it with one HTTP request.

A Live Activity is a card on your iPhone Lock Screen and Dynamic Island that you update from a script. Pick a stream_key; the first PUT starts it, later ones update it. Hook starts it remotely, so you need iOS 17.2 or later, the Hook app installed, and Live Activities allowed.

Start and update

You need an API token (hk_…).

terminal
curl -X PUT https://gethook.app/api/live-activity/stream/deploy \
  -H "Authorization: Bearer hk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "progress",
    "content_state": { "title": "Deploying api", "subtitle": "Step 2 of 5", "percentage": 40, "color": "blue" }
  }'

The reply says what happened: started, updated, orskipped when nothing changed. Common fields for every type: title(required, 120 characters), subtitle, message (300),color (blue, green, red, orange, yellow, purple, pink, teal, gray or#rrggbb), icon (an SF Symbol name) and badge.

End one

DELETE ends it. Send a final content_state to show the result, andauto_dismiss_minutes (0–240, default 2) to say how long it stays.

terminal
curl -X DELETE https://gethook.app/api/live-activity/stream/deploy \
  -H "Authorization: Bearer hk_…" \
  -H "Content-Type: application/json" \
  -d '{ "content_state": { "title": "Deployed", "percentage": 100, "color": "green" }, "auto_dismiss_minutes": 5 }'

Types

Seven types. Each needs the field shown on top of the common ones.

typeFields
valuevalue (required)
statsmetrics: 1–6 of { label, value, unit? }
metricsmetrics: 1–6 of { label, value, unit? }
progresspercentage, 0–100 (required)
segmented_progressnumber_of_steps (1–12) and current_step
timerend_date (ISO 8601 or epoch) or duration_seconds
alerttitle and message only

Buttons

Add action, and secondary_action on alert, progress and segmented_progress. Each is { title, type, url } withtitle up to 30 characters. The type is:

  • open_url (default) opens an http(s) link or a shortcuts:// URL.
  • webhook makes Hook send the request when the button is tapped. Addmethod (GET or POST) and body.
json
{
  "type": "alert",
  "content_state": { "title": "Deploy failed", "message": "api, step 3", "color": "red" },
  "action": { "title": "Logs", "type": "open_url", "url": "https://ci.example.com/42" },
  "secondary_action": { "title": "Retry", "type": "webhook", "url": "https://ci.example.com/retry/42" }
}

Without a token

Your workspace URL is already a secret, so a script that has it can start and end activities without a token. The body is the same.

terminal
curl -X PUT https://gethook.app/workspace/{workspace_key}/live/backup \
  -d '{"type":"timer","content_state":{"title":"Backup","duration_seconds":600}}'
curl -X DELETE https://gethook.app/workspace/{workspace_key}/live/backup

Limits and errors

  • Update at most once a minute. More often still works, but the reply carries a warning because iOS may throttle it.
  • 120 live and metric calls a minute per user.
  • A stream key is 1–64 letters, digits, dots, dashes or underscores.
  • 409 no_device: no iPhone can show it yet. Open Hook on iOS 17.2+ and allow Live Activities.
  • 400 invalid_content_state: the field in the reply names what to fix.

Something wrong on this page? Email office@swiftapps.us.