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 resets a stored image choice whose provider is no longer reachable to off |
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 |