# REST API

Daemon 僅綁定 `127.0.0.1:17989`——區網 client 無法連到。Port 固定，不可設定。

同一個 daemon 在 `/` 提供 web 儀表板。儀表板在編譯時內嵌進執行檔，因此 `http://127.0.0.1:17989` 就是全部介面——沒有託管在外的前端。開發時可用 `AGENVOY_PAGE_DIR` 把內嵌版本換成磁碟上的檔案（`make dev`）。

自 v1.0.1 起儀表板可離線運作。`GET /sw.js` 提供 service worker，把內嵌資產預先快取到帶版本號的 cache；`GET /vendor/*` 則從 `~/.config/agenvoy/vendor/` 提供第三方資產（QuickUI、Font Awesome、Material Symbols，以及 nanomd／voice 腳本），該目錄由 daemon 啟動時下載一次，執行檔版本變動時重新下載。頁面載入不會向 CDN 取任何東西。在 `AGENVOY_PAGE_DIR` 模式下 `/sw.js` 改為提供一支自我卸載的 worker，清掉自己的 cache 並解除註冊，避免開發版被舊快取蓋掉。

標記 **local** 的端點另外要求請求來自 `127.0.0.1`/`::1`（`localhostOnly()` 守門）。這些端點管理憑證、設定檔或行程生命週期，設計對象是同機儀表板，不是遠端 client。未匹配的路由也套用同一道守門：未知的 `/v1/` 路徑回 JSON 404，其他未知路徑則回退到儀表板首頁。

## Agent 執行

| Method | 路徑 | 說明 |
|---|---|---|
| `POST` | `/v1/send` | 執行一次 agent 請求 |
| `POST` | `/v1/chat/completions` | 無狀態、相容 OpenAI 的 chat completion |
| `GET` | `/v1/info/version` | 編譯時寫入的版本（`{version, dev}`）；未打 tag 的組建 `dev` 為 true |
| `GET` | `/v1/log` | SSE 串流。不帶 query 時只送 daemon `slog` 記錄（`EventDaemonLog` frame，`source` 即 level）——與 TUI 標題列同一路資料。其中包含新對話驗證碼，因此 daemon frame 只提供給 loopback 呼叫端。`?sessions=a,b` 在同一條連線附加這些 session 的事件；`replay=0` 跳過回補、`daemon=0` 去掉 daemon frame。遠端呼叫端必須帶 `sessions` |
| `GET` | `/v1/daemon` | **local** — `daemon.log` 原始內容 |
| `GET` | `/v1/system/update` | **local** — v1.0.11 新增。回 `{version, latest, update_available}`；`latest` 以追蹤 GitHub `releases/latest/download/x` 轉址取得（查不到時回 502 並附目前執行中的 `version`）|
| `POST` | `/v1/system/update` | **local** — v1.0.11 新增。開一個終端機視窗執行 `agen update`，回 `202 {status:"opened"}`；更新本身跑在該終端機內，不在 daemon 內。macOS 用 Terminal.app、WSL 啟動 Windows 終端機、Linux 依序嘗試 `xdg-terminal-exec`、`x-terminal-emulator`、`gnome-terminal`、`konsole`、`xfce4-terminal`、`kitty`、`alacritty`、`wezterm`、`xterm`。找不到可用終端機回 501 |
| `GET` | `/v1/mcp/tools` | 列出已連線 MCP server 註冊進來的工具（`mcp__*`） |

### `POST /v1/send` 語意

Body 為 `{content, session_id?, sse?, model?, skill?, work_dir?, system_prompt?, exclude_tools?, persist?}`，`content` 必填。若 session 仍在執行中，新請求會以 steer 訊息附加到該次執行，而不是另起一次。

| `persist` | `session_id` | 結果 |
|---|---|---|
| `false`（預設） | 空 | 建立 `temp-<uuid>`，30 分鐘無變動後刪除 |
| `true` | 空 | 建立 `chat-<uuid>`，保留 |
| 任意 | 有給 | 使用指定的 `session_id`（忽略 `persist`） |

`chat` 旗標與 `http-` 前綴已於 v1.0.11 移除：以 HTTP 建立的持久 session 改用儀表板同樣的 `chat-` 前綴，所有非 CLI 的持久 session 統一成同一種前綴。既有的 `http-` session 仍可透過 `session_id` 指名繼續使用。

```bash
curl --fail-with-body -sS \
  -H 'Content-Type: application/json' \
  -d '{"content":"List the available tools","persist":false}' \
  http://127.0.0.1:17989/v1/send
```

`/v1/chat/completions` 為無狀態：需要延續脈絡時，每次請求都要帶上先前訊息。`reasoning_effort` 接受 `none` `low` `medium` `high` `xhigh` `max`（以及別名 `minimal` `extra` `ultra`）；省略或無法辨識的值會回退到該 session 的 reasoning 設定。