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/mcp/tools`	列出已連線 MCP server 註冊進來的工具（`mcp__*`）

`POST /v1/send` 語意

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

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

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 設定。

模型

Method	路徑	說明
`GET`	`/v1/models`	列出已註冊模型（OpenAI `{data:[...]}` 格式，含 `auto`）
`GET`	`/v1/models/*id`	讀取單一已註冊模型
`POST` `DELETE`	`/v1/models` · `/v1/models/*name`	local — 新增 / 移除模型
`GET` `POST`	`/v1/model`	local — 模型路由集中在一個物件：`dispatcher`、`summary`、`image`、`stt`、`tts`，讀取時另附 `image_options`、`image_providers` 與 `audio_providers`。欄位分兩種值：`dispatcher`、`summary`、`stt`、`tts` 填模型名（`prefix@model`）—— 其中 `stt` 與 `tts` 取自 `GET /v1/model/audio`，不是 session 模型註冊表；`image` 填 provider 端點（`openai`、`codex`、`grok`、`grok-oauth`、`gemini`），因為各 provider 的圖像模型固定在 `go-llm-router` 內。`image_options` 只列出目前握有憑證的 provider，`image_providers` 與 `audio_providers` 則是完整清單（`audio_providers` 為 `openai`、`gemini`）。`POST` 為部分更新——未帶到（或 `null`）的欄位不動，`""` 清除，`image` 另接受 `off` 作為 `""` 的別名。未註冊的模型、未知的 provider、或沒有憑證的 provider 一律拒絕且不寫入
`GET`	`/v1/model/audio`	local — `stt_options` 與 `tts_options`：以目前已存憑證實際可用的 speech-to-text 與 text-to-speech 模型，向 OpenAI 與 Gemini 即時查詢後以 `provider@model` 回傳。`POST /v1/model` 的 `stt` / `tts` 只接受這些值
`GET` `POST`	`/v1/model/priority`	local — 已註冊模型的 fallback 順序。`GET` 回傳 `models`（依序的模型名）、`tiers`（`model_tag` map，模型 → tier）與 `tier_options`（`{tier, detail}` 列，第一列為代表無 tier 的 `""`）。`POST` `{models}` 把列出的模型依序移到最前，其餘接在後面；未知模型名回 400
`POST`	`/v1/model/tier`	local — `{model, tier}`。設定單一已註冊模型的 tier：`S`、`A`、`B`、`C` 或 `pass`（auto routing 與 subagent 永不選用、fallback 排最後）；`""` 清除。未註冊的模型或未知 tier 回 400

Session

Method	路徑	說明
`GET`	`/v1/sessions`	列出 session 與狀態
`GET`	`/v1/usage`	local — 跨 session 的 24 小時 / 7 天 / 28 天總 token 用量
`POST`	`/v1/session`	local — 建立 session；`{prefix}` 預設為 `cli-`
`GET` `POST` `DELETE`	`/v1/session/:id`	local — 單一 session 的完整狀態：`id`、`self_id`、`name`、`rule`、`state`、`model`、`reasoning`、`levels`、`count`。`POST` 為部分更新——`self_id` / `name` / `rule` / `model` / `reasoning` 皆選填，未帶到（或 `null`）的欄位不動；`model: ""` 重設為 `auto`，`reasoning` 必須是 `levels` 之一。`self_id` 重複回 409。`DELETE` 移除 session 目錄、歷史、狀態與向量。`GET` 另支援 `?chat=1` 在 `chat` 附上原始 action log、`?usage=1` 在 `usage` 附上每模型 token 用量；兩者預設關閉，因為 log 可能很大
`POST`	`/v1/session/:id/event`	local — 對某 session 的串流發布事件
`POST`	`/v1/session/:id/memory`	local — 由 `action` 決定的單一記憶操作：`summary` 重建滾動摘要並回傳 `count`；`compact` 丟棄較舊訊息並回傳 `removed`；`reset` 清空對話並回傳 `removed`，且必須帶 `mode`——`summary` 保留滾動摘要、`all` 一併清除
`POST`	`/v1/session/:id/cancel/:task_hash`	取消單一執行中任務。該 task hash 在本行程執行中時回 `{ok, cancelled:true}`；否則（或傳 `current`）會在 session 串流記錄一筆 canceled 事件並回 `{ok, cancelled:false, stale:true}`
`POST`	`/v1/session/:id/confirm/:confirm_hash`	回覆待決的工具確認：`{approve, remember?, allow_turn?, abort?, reason?, password?}`。確認已被回覆或已過期時回 410。核准帶有 `restricted` 路徑的確認必須來自 loopback（否則 403），並以 `password` 通過作業系統密碼驗證（失敗回 401）；sudo ticket 仍有快取時略過驗證，確認事件以 `password_cached` 標示

待決與已完成任務

Method	路徑	說明
`GET`	`/v1/session/:id/task`	列出可續行的待決（`ask_user` / confirm）任務。仍在執行中的任務會被排除——執行中的 run 每 55 秒刷新 ToriiDB 的 `action:<session_id>:<task_hash>`（TTL 60 秒，v0.35.3），因此視窗關閉或行程被砍留下的任務會在一分鐘內重新出現
`GET`	`/v1/session/:id/task/:task_hash/questions`	取得待決任務的提問
`POST`	`/v1/session/:id/task/:task_hash/resume`	回答待決任務並續行
`DELETE`	`/v1/session/:id/task/:task_hash`	不回答，直接丟棄待決任務
`GET`	`/v1/session/:id/task/history`	local — 該 session 已完成的任務，最新在前：每列 `{task_hash, end_at, objective, model, reasoning}`。`?keyword=` 對 objective 與記錄的 action 內容過濾
`GET`	`/v1/session/:id/task/:task_hash/history`	local — 單一已完成任務的完整 action 記錄，以 JSON 字串放在 `content`。該 hash 無記錄時回 404

頻道

Method	路徑	說明
`GET`	`/v1/channel`	local — 一次讀取所有頻道：`telegram` 與 `discord` 各帶 `{enabled, username, has_token}`，`admin` 帶 `{channel, authorized, chats:[{value,type,id,name}]}`。`chats` 來自 `.telegram` / `.discord` 授權檔（tg 在前、dc 在後），每個 `value` 可原樣回填；`authorized` 表示目前的轉發目標是否仍在清單上（手動輸入的 ID 會是 `false`）
`POST`	`/v1/channel/telegram` · `/v1/channel/discord`	local — `{action:"enable"\|"disable", token?}`。啟用只儲存 token 並翻轉設定旗標；TUI 會做的 `GetMe` 驗證在此刻意省略，因為 daemon 既有的設定檔 watcher 已會重連 bot 並補上 username
`GET`	`/v1/channel/:channel/chats`	local — `telegram` / `discord` 已完成驗證的對話。只在 bot 執行時有意義，請在頻道回報 `enabled` 後再查
`DELETE`	`/v1/channel/:channel/chat`	local — `{id}`。從授權檔移除一筆對話；該對話需重新驗證 bot 才會回應。id 不在清單上時回 404
`POST`	`/v1/channel/admin`	local — `{value:"tg@<chatID>"\|"dc@<channelID>"\|""}`。設定新對話驗證碼的轉發目標，空字串為清除。`value` 為必填（省略回 400，避免空 body 靜默清除設定）。只驗證格式——未在授權清單中的 ID 會讓轉發只寫 log 並記一則警告

檔案與憑證

Method	路徑	說明
`GET` `PUT`	`/v1/file`	local — 讀 / 寫檔案
`GET`	`/v1/file/open`	local — 以作業系統預設程式開啟檔案或 URL
`GET`	`/v1/file/locate`	local — 依裸檔名尋找候選路徑（`name`，另可加 `dir=1`、`child`、`size`、`mtime` 過濾）
`GET`	`/v1/workdir`	local — 解析並驗證工作目錄（`?path=`），回傳絕對路徑
`GET` `DELETE`	`/v1/key`	local — 檢查 / 刪除 keychain 中的單一憑證
`GET` `POST`	`/v1/keys`	local — 列出 / 設定憑證

Provider

Method	路徑	說明
`GET`	`/v1/providers`	local — 列出 provider 與其可用的認證方式。每筆另帶 `logged_in`，僅在三個 OAuth provider（`codex`、`copilot`、`grok-oauth`）目前持有 token 時為 true
`GET`	`/v1/providers/quota`	local — `codex`、`grok-oauth`、`copilot`、`ollama-cloud` 的剩餘額度（`kind:"percent"`）與 `openrouter`、`deepseek` 的剩餘餘額（`kind:"balance"`），以 provider 為 key 放在 `quota` 下回傳，並行查詢、10 秒上限。v0.35.3 起由 `/v1/providers/usage` 更名而來。成功的讀取在 ToriiDB 快取 3 分鐘並標記 `cached:true`；`?refresh=1` 丟棄快取重讀，儲存 key 或完成 OAuth 登入也會自動清掉該 provider 的快取。沒有憑證的 provider 回 `error` 而非 `value`，且不快取
`POST`	`/v1/provider/:provider/key`	local — 設定 API key
`GET`	`/v1/provider/:provider/oauth`	local — SSE device-code OAuth 流程。登入期間保留既有 token，因此中途放棄或失敗的重新登入不會把該 provider 登出
`DELETE`	`/v1/provider/:provider/oauth`	local — 清除已儲存的 provider 登入（`codex`、`copilot`、`grok-oauth`）。token key 屬於 OAuth 函式庫，因此走它們自己的 `ClearToken` 而非 `DELETE /v1/key`
`GET`	`/v1/provider/:provider/models`	local — 列出該 provider 可用的模型。自訂相容 provider 實例會即時向其端點探查模型清單（探查失敗回 502）

MCP

Method	路徑	說明
`GET` `POST`	`/v1/mcp`	local — 列出 / 新增 MCP server。`GET` 另回傳 HTTP server 的 `oauth: {name: bool}`，表示哪些已持有 token
`POST`	`/v1/mcp/remove`	local — 移除 MCP server
`GET`	`/v1/mcp/status`	local — 各 server 的連線狀態
`POST`	`/v1/mcp/reconnect`	local — 重連所有 MCP client 並重新註冊工具
`GET`	`/v1/mcp/oauth?name=X`	local — 單一 HTTP MCP server 的 SSE OAuth 登入，流程與 provider 相同：先送 `{"url":...}` 供瀏覽器開啟，再送 `{"done":true,"ok":...}`（登入後重連失敗時附 `reconnect_error`）。10 分鐘或 client 斷線後逾時
`POST`	`/v1/mcp/oauth/callback`	local — `{name, url}`。瀏覽器無法連到 daemon 在 `localhost:17988` 的 loopback listener 時，把 redirect URL 貼回來；code 由 URL query 解析。沒有等待中的登入時回 400
`POST`	`/v1/mcp/oauth/client`	local — `{name, client_id, client_secret?, redirect_uri?}`。為拒絕動態註冊的 server 儲存預先註冊的 OAuth client；`redirect_uri` 預設 `http://localhost:17988/callback`，必須與 provider console 完全一致。會先清除既有 token
`DELETE`	`/v1/mcp/oauth`	local — `{name}`。同時清除該 server 的 token 與 client 註冊

規則、筆記與 Skill

Method	路徑	說明
`GET`	`/v1/rules`	local — 列出存放於 `prompts/` 的 `.md` session prompt 規則
`GET`	`/v1/rule/*name`	local — 讀取單一規則
`POST` `PATCH` `DELETE`	`/v1/rule`	local — 建立 / 更新（可選 `rename`）/ 刪除規則
`GET`	`/v1/notes`	local — 於 `notes` 列出操作者筆記（name、size、`updated_at`）；記錄存在 SQLite `note` 表，不落磁碟
`GET`	`/v1/note/*name`	local — 讀取單一筆記（`name`、`content`、`updated_at`）
`POST` `PATCH` `DELETE`	`/v1/note`	local — 建立 / 更新（可帶 `rename`）/ 刪除筆記。省略 name 時以第一行為名，長度上限 32 字元
`GET`	`/v1/skills`	local — 列出已安裝的 skill
`GET`	`/v1/skill/*name`	local — 讀取單一已安裝 skill：`name`、`description`、`path`、`source`、`content`、`deletable`，另加 `files` —— 該 skill 的 `scripts/`／`references/`／`assets/` 底下所有 UTF-8 檔案，以 `{path, content}` 依路徑排序回傳，跳過隱藏檔、超過 256 KiB 者略過（v1.0.2）
`DELETE`	`/v1/skill`	local — 移除單一已安裝 skill

/v1/knowledge* 於 v0.35.4 更名為 /v1/note*；儲存層於 v0.35.3 由 ToriiDB 移至 SQLite。既有筆記於 daemon 啟動時遷移。

自動化

Cron 與一次性任務合併為同一組介面。原本分離的 /v1/cron* 與 /v1/task* 已於 v0.33.6 由 /v1/schedule 取代，以 type=cron|task 區分。

Method	路徑	說明
`GET`	`/v1/schedule`	local — 將 cron 條目與一次性任務合併成一個 `schedules` 陣列，各自標記 `type=cron\|task`；`?type=` 可只取其一
`GET`	`/v1/schedule/*skill`	local — 讀取 scheduler skill：`name` 與 `body`，其中 `body` 自 v1.0.2 起是含 frontmatter 的原始 SKILL.md，不再是解析掉 frontmatter 的主體。`files` 以與 `GET /v1/skill/*name` 相同的規則附上該 skill 的 `scripts/`／`references/`／`assets/` 內容。`description` 欄位已移除
`POST` `PATCH`	`/v1/schedule`	local — 以 `name` / `content` 建立或更新 scheduler skill，並把整組條目重新綁到 `type=cron\|task`；切換 type 會丟棄該 skill 在另一種型別下持有的條目。`description` 已於 v1.0.2 移除。`content` 若本身就以 `---` frontmatter 開頭則原樣寫入；否則由 server 端補上最小的 `---\nname: <name>\n---` 標頭
`DELETE`	`/v1/schedule`	local — 刪除某 skill 的條目（`type` 可縮限其一，省略則兩者皆移除）；若無其他綁定則一併把 skill 移入垃圾桶
`POST`	`/v1/schedule/run`	local — 立即觸發一則排程（`202 Accepted`）

允許清單

Method	路徑	說明
`GET` `POST`	`/v1/allowlist`	local — 兩份允許清單合成一個物件：`skill` 與 `tool`。`GET` 對 skill 區塊讀 `?scope=global\|project`（`project` 需帶 `?work_dir=`），對 tool 區塊以 `?prefix=` 縮限。`POST` 接受 `{skill: {name, scope?, work_dir?}}` 切換單一 skill，以及 / 或 `{tool: {prefix, entries}}` 只替換該 prefix 的自動核准條目（與 TUI `/mcp` → permission 同一支呼叫），其他規則保持不變；每個條目都必須以 `prefix` 開頭，`prefix*` 會收斂其餘條目。未帶到的區塊不動

設定

Method	路徑	說明
`GET` `POST`	`/v1/config/startup`	local — 開機自動啟動。`GET` 回傳 `enabled`（記錄的設定）與 `installed`（launchd agent 或 systemd user unit 是否存在）。`POST` `{enable}`（必填）寫入或移除 launchd agent（macOS）或 systemd user unit（Linux），回傳 `{ok, enabled, installed, detail}`；不會啟動或停止執行中的 daemon，下次登入才生效
`GET` `POST`	`/v1/config/system`	local — 回覆語言。`GET` 回傳 `reply_lang`（預設 `auto`）與 `languages`（`{code, label}` 選項，`auto` 在前）。`POST` `{reply_lang}`（必填）會正規化語言代碼，超過 64 bytes 或含換行者拒絕，並把 `reply_lang` 寫入 `config.json`
`GET` `POST`	`/v1/config/output_dir`	local — 輸出目錄。`GET` 回傳 `output_dir`（原始設定）與 `resolved`（實際使用的目錄；未設定且 `~/Downloads` 存在時即為該目錄）。`POST` `{output_dir}`（必填）展開 `~`、建立目錄後寫入 `config.json`；`""` 還原預設

其他 :target 一律回 404。

檢視

Method	路徑	說明
`GET`	`/v1/torii/error`	local — 讀取工具錯誤記憶。模式由 `keyword` 單獨決定：沒帶 `keyword` 就是列出（`?tool=` 可把列表縮到單一工具，`?limit=` 預設 50），帶了才走搜尋（`?limit=` 預設 16）。v1.0.1 之前只帶 `?tool=` 會落到搜尋路徑而回空
`PATCH`	`/v1/torii/error`	local — `{id, action}`，皆必填。替換單筆錯誤記憶的 action 並以 `record` 回傳；id 不存在時回 404

/v1/toriidb HTTP 入口已於 v0.35.3 移除。自 ToriiDB v0.6.2 起，所有行程改走 ToriiDB 自己的 socket，工具快取、對話向量、錯誤記憶與待決任務存活訊號無需經過 HTTP 即可共用。