Skip to main content
The Models domain exposes the global catalog of language models the platform knows about. External integrations use it to look up a model identifier and its recorded catalog state before authoring or updating an agent definition. The catalog is the same for every caller. It does not say whether a particular agent may run on a model: agent allowlists and enabled-provider resolution are answered by listAvailableModelsForAgent.

Resource shape

Both operations return the Model schema, an explicit allowlist of exactly seven fields. Every field is always present: isActive and status are the catalog’s recorded state. They are not a promise that an agent can execute on the model, and they do not report provider health. A catalog field with no recorded value is returned as null; status is never inferred from isActive. The response never includes pricing, pricing provenance, provider-specific attributes, synchronization details, internal storage identifiers, or which agents use a model. Earlier responses echoed the full internal catalog row, including an id field, costs, and assignedAgents; those undocumented fields were removed. Use modelId as the identifier. A model’s full metadata, and its rates for a gateway:read holder, are getModelDetail; the agents using a model are GET /api/v3/agents?modelId=.

Operations

Reads:
  • GET /api/v3/models — listModels — list catalog entries
  • GET /api/v3/models/{modelId} — getModel — fetch a single catalog entry by modelId
  • GET /api/v3/models/{modelId}/detail — getModelDetail — one model’s full metadata, its rates under gateway:read
  • GET /api/v3/model-fallback-chains — listFallbackChains — the model fallback chains
All require the agents:read scope; getModelDetail and listFallbackChains decide it at the platform scope. getModel answers 404 resource_missing when id is missing or matches no catalog entry.

Common workflows