# Provider Endpoints

Endpoints for provider catalogs, logins, credentials, quota and model lists.

| Method | Path | Description |
|---|---|---|
| `GET` | `/v1/providers` | **local** — list providers and their available auth methods. Each row also carries `logged_in`, true only for the OAuth providers (`codex`, `copilot`, `grok-oauth`) that currently hold a token and for `claude-code` while it is enabled, `hidden` (v1.1.0; true for `claude-code` unless the daemon was started with `agen --enable-claude-code`, which needs a stopped daemon — `agen stop` first), and (since v1.0.22) `console`, the sorted page names that `/v1/provider/:provider/console` serves for it (`key` / `billing` for API-key providers, `plan` for subscriptions, empty for `compat`) |
| `GET` | `/v1/providers/quota` | **local** — remaining quota for `codex`, `grok-oauth`, `copilot`, `ollama-cloud`, and `claude-code` since v1.1.0 (`kind:"percent"`) and remaining credit for `openrouter`, `deepseek` (`kind:"balance"`), returned under `quota` keyed by provider and fetched in parallel with a 10 s ceiling. Renamed from `/v1/providers/usage` in v0.35.3. Successful reads are cached in ToriiDB for 3 minutes and come back flagged `cached:true`; `?refresh=1` drops the cache and re-reads, and saving a key or finishing an OAuth login drops that provider's entry on its own. Providers without a credential come back with `error` instead of `value` and are never cached |
| `POST` | `/v1/provider/:provider/key` | **local** — set an API key |
| `GET` | `/v1/provider/:provider/oauth` | **local** — SSE device-code OAuth flow. An existing token is left in place while the login runs, so an abandoned or failed re-login no longer logs the provider out |
| `DELETE` | `/v1/provider/:provider/oauth` | **local** — clear a stored provider login (`codex`, `copilot`, `grok-oauth`). The token keys belong to the OAuth libraries, so this goes through their own `ClearToken` rather than `DELETE /v1/key` |
| `GET` | `/v1/provider/:provider/models` | **local** — list models available to this provider. For a custom compatible provider instance the model list is probed live from its endpoint (502 when the probe fails). Since v1.0.15 the response also carries `windows`, a `{model: {in, out}}` map of context-window sizes for the models the window table knows; a model with no entry is simply absent from the map. Since v1.0.18 the list is cached in ToriiDB for 15 minutes per provider and dropped as soon as that provider's key is set, its OAuth completes, or its login is cleared |
| `GET` | `/v1/provider/:provider/console` | **local** — added in v1.0.22. `302` redirect to the provider's console page; `?page=` is `key`, `billing` or `plan`, defaulting to `plan` for subscription providers and `key` otherwise. 404 when the provider has no such page. The TUI (`o` in `/model add`) and the dashboard's Console / Plans links go through it, so the URLs live in one table (`providerConsole` in `handler/providers.go`) |