Skip to content

Reference

Dashboard API·

Every HTTP and WebSocket route of the cockpit dashboard, generated from dashboard/server.py with its gate (public / key) and body fields — filterable, each route linkable.

  • the iOS app · curl · personas off-robot
  • 3 min
  • 639 words
  • from the code
  • verified 2026-09-21

In 10 seconds

  • Generated from dashboard/server.py + dashboard/auth.py at every build; gate is what _gate decides.
  • /api/health is the only public route. Writes need a same-origin Origin (403) and REACHY_RATE_LIMIT (5/s → 429).
  • /ws carries state, agent_log (brain rows by persona) and event receipts.
key how who
owner bearer Authorization: Bearer $REACHY_TOKEN, or ?token= for <img>/WebSocket iOS app, curl, personas off-robot
passkey WebAuthn cookie, 12 h; first enrolment TOFU, later ones need REACHY_REG_TOKEN the owner's browser
loopback 127.0.0.1, no cf-connecting-ip — reads everywhere, writes on /api/tracking* reachy_camera.py, head_tracking.py
COCKPIT=http://127.0.0.1:8097          # on the robot; off it, your own tunnel or SSH forward
curl -s $COCKPIT/api/health | jq .ok                                                      # public
curl -s -H "Authorization: Bearer $REACHY_TOKEN" $COCKPIT/api/state | jq .head            # key
curl -s -H "Authorization: Bearer $REACHY_TOKEN" -H 'Content-Type: application/json' \
     -d '{"name":"cheerful1"}' $COCKPIT/api/control/express

Routes·

Health & state·

method path params gate (✅ public · 🔒 key) what
GET /api/ask/last — 🔒 Is an Ask running; the last answer. ↗
GET /api/emotions — 🔒 The daemon's recorded-move library (81 on 1.10). ↗
GET /api/health — ✅ Liveness, daemon, camera, fd pressure. Public. ↗
GET /api/log n: int, after: int 🔒 Agent-log tail (n ≤ 300, after = row id). ↗
GET /api/state — 🔒 Full robot state: pose, motors, services, tracking. ↗
GET /api/telemetry — 🔒 State + camera — the endpoint-device telemetry action. ↗

Camera·

method path params gate (✅ public · 🔒 key) what
GET /api/camera/snapshot — 🔒 Alias — the endpoint-device snapshot action. ↗
GET /api/snapshot.jpg — 🔒 Latest JPEG (503 while none). ↗
GET /api/stream — 🔒 MJPEG — one daemon client for every viewer. ↗

Control·

method path params gate (✅ public · 🔒 key) what
POST /api/control/antennas JSON 🔒 Antenna angles, degrees. ↗
POST /api/control/ask JSON 🔒 Dashboard Ask turn → /ws agent_log rows. ↗
POST /api/control/demo JSON 🔒 on: true pauses tiny-thinker. ↗
POST /api/control/express JSON 🔒 Play a recorded move by name. ↗
POST /api/control/home — 🔒 Neutral pose. ↗
POST /api/control/look JSON 🔒 Head pose (clamped), optional antennas, body_yaw, duration. ↗
POST /api/control/motors JSON 🔒 mode: enabled · disabled · gravity_compensation. ↗
POST /api/control/reel JSON 🔒 Showcase reel: start or abort. ↗
POST /api/control/say JSON 🔒 Piper TTS with head wobble → {engine, seconds}. ↗
POST /api/control/sleep — 🔒 Sleep pose, motors relaxed. ↗
POST /api/control/stop — 🔒 E-stop: cancel the running move. ↗
POST /api/control/volume JSON 🔒 Speaker level 0–100. ↗
POST /api/control/wake — 🔒 Motors on, wake emote. ↗

Ask / chat·

method path params gate (✅ public · 🔒 key) what
POST /api/chat JSON 🔒 One fleet agent turn; waits ≤ 75 s. ↗

Perception·

method path params gate (✅ public · 🔒 key) what
GET /api/tracking — 🔒 Face-tracking status: detected, x/y, holds, paused. ↗
POST /api/tracking JSON 🔒 Tracker on/off (enabled); loopback ok. ↗
POST /api/tracking/hold JSON 🔒 Named hold (name, on, ttl) while TINY speaks. ↗

Settings·

method path params gate (✅ public · 🔒 key) what
GET /api/config — 🔒 Settings schema, values, catalog. ↗
PUT /api/config JSON body 🔒 Write settings (voice keys restart the session). ↗
GET /api/config/preview/{persona} persona: str 🔒 Composed prompt and tools. ↗
DELETE /api/config/{key} key: str 🔒 Reset key to env. ↗
GET /api/personas — 🔒 Units: state, pid, journal tail. ↗
POST /api/personas/{unit}/restart unit: str 🔒 Restart unit; 30 s cooldown. ↗

Auth·

method path params gate (✅ public · 🔒 key) what
GET /api/auth/credentials — ✅ List passkeys (owner). ↗
DELETE /api/auth/credentials/{cid} — ✅ Remove a passkey (owner). ↗
POST /api/auth/login/begin — ✅ WebAuthn assertion options. ↗
POST /api/auth/login/complete — ✅ Verify, set the session cookie. ↗
POST /api/auth/logout — ✅ Drop the session cookie. ↗
POST /api/auth/register/begin — ✅ WebAuthn registration options (TOFU, then REACHY_REG_TOKEN). ↗
POST /api/auth/register/complete — ✅ Store the new passkey. ↗
GET /api/auth/status — ✅ Who am I; is TOFU enrolment open. ↗

Realtime·

method path params gate (✅ public · 🔒 key) what
WS /ws sock: WebSocket 🔒 State at REACHY_WS_HZ + agent_log + events; anonymous → 4401. ↗

Shell·

method path params gate (✅ public · 🔒 key) what
GET / — ✅ The SPA shell (no-cache). ↗
GET /{path:path} path: str ✅ Static assets / SPA fallback. ↗

Other·

method path params gate (✅ public · 🔒 key) what
GET /api/doa — 🔒 Turn-toward-speaker status and why not.
POST /api/doa JSON 🔒 {enabled} — turn toward speech (K); loopback ok.

45 routes · 11 public.