Live Activities

For a long-running task (deploy, build, batch job), show one live status card on the lock screen and Dynamic Island instead of a stream of notifications. Three Bearer-authed calls; correlation_id is the card’s handle. Needs the Pidge iOS app (iOS 18+); no-ops gracefully otherwise.

By default each activity is an entry of the user’s one consolidated status card: two agents running jobs are two rows on the same card, never a pile of stacked banners. A finished entry flips to ✓ with its outcome line, lingers ~30 seconds, then leaves on its own — and the server retires stale activities by itself. presentation: "dedicated" opts into an own card (budget: 2 active per user; over budget the write still lands as a consolidated entry, with degraded: true on the echo).

Start

curl -X POST $PIDGE_URL/api/v1/live_activities \
  -H "Authorization: Bearer $PIDGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"correlation_id":"deploy-42","title":"Deploy pidge-api",
       "status":"Building…","symbol":"hammer.fill","progress":0.25}'

Re-POSTing the same correlation_id upserts — it updates an active card or restarts an ended one, never duplicates.

Update (partial — send only what changed)

curl -X PATCH $PIDGE_URL/api/v1/live_activities/deploy-42 \
  -H "Authorization: Bearer $PIDGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"Running migrations…","progress":0.6,"detail":"3/5"}'

End

curl -X POST $PIDGE_URL/api/v1/live_activities/deploy-42/end \
  -H "Authorization: Bearer $PIDGE_TOKEN" -H "Content-Type: application/json" \
  -d '{"outcome":"Deployed · 221 tests green","done":true}'

Send the final snapshot explicitly on /end — an end can also be a cancellation at 50%. outcome is the line shown next to the ✓ (falls back to the final status); linger_seconds (default 30) controls how long the finished entry stays visible. Ending is idempotent.

Fields

Field	Meaning
title	required — the card’s headline
status	current step (“Building…”)
symbol	SF Symbol name (hammer.fill, shippingbox, …)
progress	0.0–1.0 → progress bar; omit for indeterminate
progress_label	fraction shown with the bar (“3/5”)
detail	small trailing value
started_at	ISO8601 → live elapsed timer
ends_at	ISO8601 → live countdown; at zero the server concludes the entry itself
done	true → ✓ styling

From the CLI, pidge live drives all of this (--step 3/5 is sugar for progress + progress_label; --end --outcome "…" concludes), and pidge event --event-at <ISO> gives you the countdown case for free: one call, and the server schedules the T−lead push and runs the countdown card itself — the human answers and the card flips to “Answered” instantly. The machine spec is in the manifest under live_activity.