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) agentsPOST /api/agents/claims—{"catalog_id","display_name?"}→ claim code +paste_messageGET /api/agents/claims/{code}→ claim status (pending/claimed/expired)POST /api/agents/{agent_id}/remove— remove an enrolled agentPOST /api/grants—{"domain":str,"tiers":[str],"categories":[str],"window":{"from":epoch,"to":epoch},"duration_days":int,"daily_cap":int}→ the created grantPATCH /api/grants/{id}— any ofcategories,daily_cap,expires_atPOST /api/grants/{id}/revoke→{"revoked": true}
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
registeredshape; 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