Models
OpenAI's list shape: the four routers first, then one entry per published catalog model under its id and one under its pinned id. Each entry has OpenAI's id, object: "model", created (the model's release, else the catalog's publication) and owned_by: "hips", then hugging_face_id, the Hugging Face repository the model was added from (null on a router), and the hips object.
/v1/modelsservedThe routers, models and deployments the key may name, with the hips extensions.
/v1/models/{id}servedOne entry of the list, by catalog id, pinned id, router name or dep_ id.
taskThe task type:
chatfor a language model, else the model's own (classification,embedding,rerank, and the others of the task API).modalityOn a language model,
{"input": ["text"] or ["text", "image"], "output": ["text"]};nullon any other.family, version, aliases, pinned_idsThe catalog entry's names;
pinned_idsthe version served now.statusThe model's catalog status, as published.
billing_unitThe unit the model is billed in, as the catalog sets it.
featuresThe features the model advertises, per pool:
{"certified": [...], "community": [...]}.tool_callsOn a language model, the state of its tool calls per pool and at their best:
validated(tested and passed),template(its chat template takes tools, not tested yet) ornone. Hosted tools needvalidatedin the pool the request resolves to.nullon any other model.poolsThe supply state per pool under no requirements:
available,limited,unavailableorunknown. A snapshot, never a reservation; stale becomesunknown.availabilityWhat each pool can do for your key now, in its pools and region:
{"certified": {"state", "reason", "as_of", "context_window"}, "community": {...}},stateserving(a slot is free now with the model loaded: a request is served at once),on_demand(no slot is free with it loaded, but a GPU free with it on disk loads it when asked, which can take minutes or longer, or every GPU that offers it is busy: a request waits),none(a request will not succeed now) with itsreason(not_offered,excluded,no_supply) orunknown(stale,not_read, orintermittent: a GPU offered it within the last five minutes and none does at this reading, so a request may yet succeed), neverservingfrom a stale reading.context_windowis the longest prompt the pool serves now, in tokens,nullwhere it serves none, beside the model's owncontext_length.coding_agentsOn a language model, the coding agents it works with:
{"state", "agents": {"hips_code" | "opencode" | "claude_code" | "codex": {"state", "reason"}}},statetested,requirements(meets them, not tested yet),failedornone.GET /v1/models/{id}adds each agent'stests. Each agent's name and route are said once, in the list's top-levelhips.coding_agents.lanesshared,always_onor both.pricing_modesThe pricing modes the model is sold in:
market, andstablewhere a stable price is offered.context_length, max_output_tokens, limitsThe model's limits;
limitsholds the task-specific ones (inputs per request, input bytes, an embedding model'sdimensionsandtruncatable).licenseThe model's license identifier and conditions URL.
deprecates_atFor a pinned id with a retirement date;
nullotherwise.hugging_face_revisionOn a pinned id's entry alone: the commit of the Hugging Face repository the version was made from.
allowed, allowed_byOnly on an entry an access guardrail keeps out of this key's reach:
allowed: falseandallowed_by: {"guardrail": "grd_...", "name"}; or on a model or a router the workspace's plan does not include:allowed: falseandallowed_by: {"plan": "free", "required_plan": "pro"}, the workspace's plan and the lowest plan that includes it, the plan's mark alone where both apply. Absent on every entry the key may name.routerOnly on a router's entry:
{"use_case", "type", "tasks", "preference", "suffixes": ["fast", "cheap"], "candidates", "ready"}:typeone oftext,image,audioorvideo(textfor the four),tasksthe tasks it routes (["chat"]for the four), the models it can choose for this key now and how many of them are ready (Semantic routing).
The list's own top-level hips member carries defaults, the requirements a request of this key carries when it names none (pool, pricing_mode, region, fallback, pools); pool is null for Auto, which requires no pool and chooses one per request. It also carries coding_agents, each coding agent's id, name, route and context_floor, once for the list.
Both routes answer with the key's view. A model an access guardrail keeps out of this key's reach stays listed, with hips.allowed: false and the guardrail in hips.allowed_by, and hips.defaults.pools answers the pools left; so a client can tell an unknown model from one it may not name before sending a request. A model or a router the workspace's plan does not include is listed the same way, hips.allowed_by naming the plan and the lowest plan that includes it (Billing). GET /v1/models/{id} answers a router's name with or without its suffix. The catalog is the only source of names; it lists every model HIPS has published, each with its status.
| Status | Type | Code | Situation | Retry |
|---|---|---|---|---|
| 403 | permission_error | key_scope_denied | The key's kind excludes the route: a retrieval key on any route but its batch and file reads; a key other than full writing a knowledge base's documents | No |
| 404 | not_found_error | model_not_found | Unknown catalog id, alias, pinned id or dep_; another workspace's dep_; a name starting with hips-router that is not one of the four routers | No |
- Status
- 403
- Type
permission_error- Code
key_scope_denied- Situation
- The key's kind excludes the route: a retrieval key on any route but its batch and file reads; a key other than
fullwriting a knowledge base's documents - Retry
- No
- Status
- 404
- Type
not_found_error- Code
model_not_found- Situation
- Unknown catalog id, alias, pinned id or
dep_; another workspace'sdep_; a name starting withhips-routerthat is not one of the four routers - Retry
- No
Related sheets
- Sheet
- 18 of 20
- Detail
- F
- Updated
- 2026-11-14