> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Browse the global catalog of language models and their recorded catalog state.

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](https://docs.gloo.com/forge/reference/http-api/external/listAvailableModelsForAgent.md).

## Resource shape

Both operations return the `Model` schema, an explicit allowlist of exactly seven fields. Every field is always present:

| Field | Type | Meaning |
| - | - | - |
| `modelId` | string | Canonical public identity, such as `anthropic/claude-sonnet-4-6`. Use it with `GET /api/v3/models/{modelId}`. |
| `provider` | string | Catalog provider key. |
| `displayName` | string or `null` | Human-readable name. |
| `contextWindow` | number or `null` | Context window in tokens. |
| `maxTokens` | number or `null` | Maximum output tokens. |
| `isActive` | boolean | Whether the catalog entry is recorded as active. |
| `status` | string or `null` | Recorded catalog status, such as `active` or `deprecated`. |

`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`](https://docs.gloo.com/forge/reference/http-api/models/getDetail); the agents using a model are [`GET /api/v3/agents?modelId=`](https://docs.gloo.com/forge/reference/http-api/agents/list).

## Operations

Reads:

* `GET /api/v3/models` — [listModels](https://docs.gloo.com/forge/reference/http-api/models/list.md) — list catalog entries
* `GET /api/v3/models/{modelId}` — [getModel](https://docs.gloo.com/forge/reference/http-api/models/get.md) — fetch a single catalog entry by `modelId`
* `GET /api/v3/models/{modelId}/detail` — [getModelDetail](https://docs.gloo.com/forge/reference/http-api/models/getDetail.md) — one model's full metadata, its rates under `gateway:read`
* `GET /api/v3/model-fallback-chains` — [listFallbackChains](https://docs.gloo.com/forge/reference/http-api/models/listFallbackChains.md) — 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

```bash theme={null}
curl "$FORGE_BASE/api/v3/models" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## Related

* [Agent models](https://docs.gloo.com/forge/build/define-an-agent.md) — conceptual background on model selection and routing
* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.