# Provider 端點

供應商目錄、登入、憑證、額度與模型清單的端點。

| Method | 路徑 | 說明 |
|---|---|---|
| `GET` | `/v1/providers` | **local** — 列出 provider 與其可用的認證方式。每筆另帶 `logged_in`，僅在 OAuth provider（`codex`、`copilot`、`grok-oauth`）目前持有 token、或 `claude-code` 已啟用時為 true；`hidden`（v1.1.0）對 `claude-code` 為 true，除非 daemon 以 `agen --enable-claude-code` 啟動（需先停止 daemon，`agen stop`）；v1.0.22 起另帶 `console`，為 `/v1/provider/:provider/console` 對該 provider 可用的頁面名稱（API key 類為 `key` / `billing`，訂閱制為 `plan`，`compat` 為空），已排序 |
| `GET` | `/v1/providers/quota` | **local** — `codex`、`grok-oauth`、`copilot`、`ollama-cloud`，以及 v1.1.0 起 `claude-code` 的剩餘額度（`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）。自 v1.0.15 起另回傳 `windows`，為 `{model: {in, out}}` 的 context window 大小對照；window 表沒有該模型時就不會出現在這個 map 裡。自 v1.0.18 起，各 provider 的清單在 ToriiDB 快取 15 分鐘，並於該 provider 設定金鑰、完成 OAuth 或清除登入時立即失效 |
| `GET` | `/v1/provider/:provider/console` | **local** — v1.0.22 新增。以 `302` 轉址到該供應商的 console 頁面；`?page=` 為 `key`、`billing` 或 `plan`，訂閱制供應商預設 `plan`，其餘預設 `key`。供應商沒有該頁面時回 404。TUI（`/model add` 中按 `o`）與儀表板的 Console / Plans 連結都經由此端點，網址只維護在一張表（`handler/providers.go` 的 `providerConsole`） |