Model Endpoints
Last updated
Endpoints for registered models, routing, tiers, quota and audio models.
| Method | Path | Description |
|---|---|---|
GET | /v1/models | List registered models (OpenAI {object:"list", data:[...]} shape, auto included), plus the same names as a plain models array |
GET | /v1/models/*id | Read one registered model; an unknown id returns 404 with the OpenAI model_not_found error |
POST DELETE | /v1/models · /v1/models/*name | local — POST {prefix, models} sets the whole model list of one provider prefix (a provider id from GET /v1/providers or a custom compatible instance): listed IDs not yet registered are added, registered prefix@ models missing from the list are removed, and the reply is {ok, added, removed}; auto is reserved (400). DELETE /v1/models/<prefix>@<model> removes one model (404 when unknown), moves dispatcher / summary to the first remaining model when they pointed at it, and resets sessions pinned to it to auto |
GET POST | /v1/model | local — model routing in one object: dispatcher, summary, image, decision, stt, tts, plus image_options, image_providers, decision_options and audio_providers on read. The fields hold two different kinds of value. dispatcher, summary, stt and tts name a registered model (prefix@model) — stt and tts are drawn from GET /v1/model/audio, not from the session model registry. image names an image model as provider@model since v1.0.13 — image_options is now probed from each credentialed provider (cached for 15 minutes since v1.0.18) (openai, grok, grok-oauth, gemini, and openrouter since v1.0.17) with an image-only model filter, so the choice is a model rather than an endpoint. codex is the exception and still appears as the bare provider name, and a bare provider name stored from an earlier version is still accepted. image_providers and audio_providers remain the full provider catalogs (image_providers is openai, codex, grok, grok-oauth, gemini, openrouter; audio_providers is openai, gemini, openrouter). decision (since v1.3.1) names the decision model as typesafe@<model> or openrouter@<model>, and must be one of decision_options, the decision models listed live from the credentialed TypeSafe and OpenRouter accounts (cached for 15 minutes); anything else returns 400. While a decision model is set it runs alongside dispatcher on every routed request and the first valid answer wins; "" turns it off. dispatcher_beta (added in v1.0.18) was Removed in v1.3.2: GET no longer returns it and POST ignores it. The v1.0.18 behavior — routing straight to TypeSafe, with a 400 carrying missing_key when TYPESAFE_API_KEY was absent — was Removed in v1.3.1. The global auto_reasoning toggle was removed in v1.1.0 — set a session's reasoning to auto instead, and the model selector picks the level per request from the kind of work. POST is a partial update — a field left out (or null) is untouched, "" clears it, and off is an alias of "" for image. An unregistered model, an unknown provider, or a provider with no credentials is rejected and nothing is written. GET first clears a stored image, stt or tts choice that is no longer among the models reachable with the stored credentials (a bare provider name such as codex is kept while that provider has a credential); stt and tts joined this check in v1.3.16. The same check runs after DELETE /v1/key, after DELETE /v1/provider/:provider/oauth, after a key is deleted in the TUI, and when the TUI /model image, stt or tts tab loads |
GET | /v1/model/quota | local — added in v1.1.0. ?model=<prefix>@<model> returns {quota}: that model's provider quota as a display string ("42%" for codex, grok-oauth, copilot, claude-code — since v1.1.3 one percentage per reported window joined by /, e.g. "37%/80%"; "$12.34" for openrouter, deepseek), or "" when the provider reports no quota, has no credential, or the read fails. Read live (15 s ceiling, no cache). The dashboard fetches it after a completion instead, since quota was removed from completion events and channel footers in v1.1.0 |
GET | /v1/model/audio | local — stt_options and tts_options: the speech-to-text and text-to-speech models reachable with the credentials stored right now, fetched from OpenAI, Gemini and OpenRouter (added in v1.0.17) and returned as provider@model; since v1.0.18 each provider's answer is cached for 15 minutes, with the same invalidation as /v1/provider/:provider/models. These are the only values POST /v1/model accepts for stt / tts |
GET POST | /v1/model/priority | local — fallback order of the registered models: after the selected model fails, the others are tried top to bottom. Since v1.1.0 pass-tier models are skipped (v1.0.20 through v1.0.27 still tried them at their place in the order). GET returns models (names in order), tiers (the model_tag map, model → tier) and tier_options ({tier, detail} rows, "" first for no tier). POST {models} moves the listed names to the front in that order and keeps the rest after them; an unknown name returns 400 |
POST | /v1/model/tier | local — {model, tier}. Sets one registered model's tier: S, A, B, C, or pass (since v1.1.0 never picked by auto routing or subagents, even when the request names it, and skipped by fallback; it still runs when set as a session's own model); "" clears it. An unregistered model or unknown tier returns 400 |