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_…).
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.
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.
| type | Fields |
|---|---|
value | value (required) |
stats | metrics: 1–6 of { label, value, unit? } |
metrics | metrics: 1–6 of { label, value, unit? } |
progress | percentage, 0–100 (required) |
segmented_progress | number_of_steps (1–12) and current_step |
timer | end_date (ISO 8601 or epoch) or duration_seconds |
alert | title 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 ashortcuts://URL.webhookmakes Hook send the request when the button is tapped. Addmethod(GET or POST) andbody.
{
"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.
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/backupLimits and errors
- Update at most once a minute. More often still works, but the reply carries a
warningbecause 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: thefieldin the reply names what to fix.
Something wrong on this page? Email office@swiftapps.us.