> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard API

> Loopback JSON API for the macOS shell and local dashboard SPA.

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`

```json theme={null}
{
  "node_id": "n_...",
  "mail_address": "user@example.com",
  "relay": {"configured": true, "connected": true, "hostname": "n....relay.example.com", "queued": 0},
  "sync": {"state": "idle" | "syncing" | "error", "last_completed_at": 1760000000,
            "messages": 48213, "progress": {"done": 0, "total": 0}, "error": null},
  "model": {"backend": "ollama", "chat_model": "qwen2.5:7b-instruct", "embed_model": "nomic-embed-text", "available": true},
  "paused": false,
  "pending_approvals": 1,
  "phone_paired": true,
  "audit": {"entries": 1204, "chain_ok": true}
}
```

`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=`

```json theme={null}
{
  "entries": [
    {
      "seq": 1204,
      "at": 1760000000,
      "agent_domain": "assistant.example",
      "tool": "get_upcoming_travel",
      "tier": "structured_read",
      "grant_id": "g_...",
      "decision": "allowed" | "denied" | "pending_approval" | "approved" | "rejected",
      "reason": "in_grant",
      "query": "…the agent's arguments, verbatim…",
      "email_ids": ["m_1", "m_2"],
      "email_previews": [{"id": "m_1", "subject": "Your flight", "from": "no-reply@air.example", "date": 1759900000, "category": "travel"}],
      "output": "…exactly what was returned…",
      "redactions": [{"kind": "otp", "count": 1}],
      "entry_hash": "hex", "prev_hash": "hex"
    }
  ],
  "next_cursor": "…"
}
```

`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`

```json theme={null}
{
  "agents": [
    {
      "domain": "assistant.example",
      "first_seen": 1759000000,
      "last_seen": 1760000000,
      "requests_7d": 42,
      "denied_7d": 1,
      "blocked": false,
      "keys_verified": true,
      "grants": [
        {
          "id": "g_...",
          "tiers": ["structured_read", "free_form_read"],
          "categories": ["travel", "orders"],
          "window": {"from": 1735689600, "to": 1767225600},
          "expires_at": 1762600000,
          "daily_cap": 50,
          "used_today": 3,
          "revoked": false,
          "created_at": 1759000000,
          "approved_by": "iPhone (passkey)"
        }
      ]
    }
  ]
}
```

* `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`

```json theme={null}
{
  "gmail": {"address": "user@example.com", "auth": "app_password", "imap_host": "imap.gmail.com", "connected": true},
  "relay": {"enabled": true, "url": "https://relay.example.com", "hostname": "n….relay.example.com"},
  "model": {"backend": "ollama", "endpoint": "http://127.0.0.1:11434", "chat_model": "qwen2.5:7b-instruct", "embed_model": "nomic-embed-text"},
  "stay_awake": true,
  "sync": {"interval_minutes": 5, "folders": ["INBOX", "[Gmail]/All Mail"], "history_days": 730},
  "approvals": {"push_configured": true, "push_tokens": 1},
  "backups": {"enabled": false, "path": null},
  "defaults": {"deny_by_default": true, "max_answer_chars": 600}
}
```

`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

```json theme={null}
{"error": "not_found" | "bad_request" | "unauthorized" | "conflict" | "rate_limited" | "pairing_unavailable", "detail": "human readable"}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.