Skip to main content
The dashboard is a static single-page app served by the node at http://127.0.0.1:8765/ and backed by the JSON API below. The API binds to loopback only and requires the header X-FAU-Local: <local_api_token> (written to ~/Library/Application Support/FAU/local_token by the node at first start and injected into the page by the node when it serves index.html, so the SPA can read it from window.__FAU_TOKEN__). All timestamps are epoch seconds. All list endpoints take limit (default 50, max 500) and cursor (opaque string; response includes next_cursor or null).

Status

GET /api/status
POST /api/pause — {"paused": true} → same status object. Pausing rejects every agent request with paused until resumed. POST /api/sync/run — {"full": false} → 202 {"started": true}.

Activity (audit log)

GET /api/audit?limit=&cursor=&agent=&decision=
GET /api/audit/verify → {"ok": true, "checked": 1204, "broken_at": null} GET /api/audit/export → newline-delimited JSON of the whole chain (download).

Agents and grants

GET /api/agents
  • POST /api/agents/{domain}/block — {"blocked": true}
  • GET /api/agents/catalog → {"catalog":[{"id","name","blurb","expected_publisher"}]}
  • GET /api/agents/enrolled → enrolled (Lane B) agents
  • POST /api/agents/claims — {"catalog_id","display_name?"} → claim code + paste_message
  • GET /api/agents/claims/{code} → claim status (pending / claimed / expired)
  • POST /api/agents/{agent_id}/remove — remove an enrolled agent
  • POST /api/grants — {"domain":str,"tiers":[str],"categories":[str],"window":{"from":epoch,"to":epoch},"duration_days":int,"daily_cap":int} → the created grant
  • PATCH /api/grants/{id} — any of categories, daily_cap, expires_at
  • POST /api/grants/{id}/revoke → {"revoked": true}
Revocation is immediate: the grant’s biscuit revocation id is added to the deny list.

Approvals

GET /api/approvals?state=pending|past → {"approvals": [Approval]} using the Approval shape from protocol.md §6, plus "decision", "decided_at", "decided_by" for past ones. POST /api/approvals/{id}/decide — {"decision": "once"|"30_days"|"always_category"|"deny"|"send"|"reject"}. Decisions made in the dashboard are recorded with decided_by: "dashboard (local)"; the phone path is preferred and is the only one that carries a device signature.

Categories

GET /api/categories → {"categories":[{"name":"travel","count":812,"label":"Travel"}], "never_share_senders":["bank@example.com"]} GET /api/emails?category=&q=&limit=&cursor= → {"emails":[{"id":"m_1","subject":str,"from":str,"date":epoch,"category":str,"confidence":0.82,"manual":false,"never_share":false}],"next_cursor":null} POST /api/emails/{id}/category — {"category":"orders"} (marks manual: true, used as classifier feedback) POST /api/senders/never-share — {"sender":"bank@example.com","never_share":true}

Drafts

GET /api/drafts → {"drafts":[{"id":"d_...","agent_domain":str,"to":[str],"subject":str,"body":str,"created_at":epoch,"state":"draft"|"awaiting_approval"|"sent"|"rejected","thread_ref":str|null}]} POST /api/drafts/{id}/delete

Settings

GET /api/settings / PUT /api/settings
POST /api/settings/test-gmail — {"address":str,"app_password":str} → {"ok":true,"folders":[str]} (the password goes straight to the keychain; never returned) POST /api/settings/test-push — no body → {"ok":true,"sent":n,"detail":"sent"}. Fails with 400 when no phone has registered an Expo push token. Sends a content-free test alert (kind: "test") so you can verify delivery without creating an approval. POST /api/settings/relay/register — optional {"url":"https://relay.fau.run","code":str,"wait_seconds":45}
  • Already registered → {"status":"registered","hostname":str,"node_id":str,"url":str}
  • Code found in inbox (or provided) → same registered shape; tunnel starts
  • Code not yet available → 202 {"status":"code_pending","registration_id":str,"url":str,"detail":str}
POST /api/settings/relay/confirm — {"registration_id":str,"code":str,"url":str?} → registered shape above. Default relay URL is https://relay.fau.run. Gmail must be connected first. POST /api/danger/delete-everything — {"confirm":"DELETE"} → wipes store, keys, grants, audit.

Pairing

GET /api/pair/start → {"pairing_code":"482913","qr_payload":"fau://pair?host=…&code=…&fp=…","expires_at":epoch} host is the relay hostname when one is configured, otherwise this Mac’s LAN address and dashboard port. Loopback is never used: a phone that scanned 127.0.0.1 would contact itself. If no address a phone could reach is known, the response is 503 with {"error":"pairing_unavailable","detail":"…"}. This does not change what the node binds to. The dashboard still listens on localhost; a LAN address in the payload is only a name to dial, not an open listener. GET /api/pair/devices → {"devices":[{"id":str,"name":str,"kind":"passkey","paired_at":epoch,"last_used_at":epoch}]} POST /api/pair/devices/{id}/remove

Errors

HTTP status mirrors the code (404, 400, 401, 409, 429, 503).