Skip to main content
GET
List the models an app's agent may call
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Returns the set of model IDs available to a specific agent, formatted as an OpenAI-compatible model list. This mirrors the /api/inference/v1/models response shape so you can build model-picker UIs using the same parsing logic as any OpenAI-compatible client. The endpoint resolves the target agent through one of three paths — see Agent resolution below.

Request

Headers

Query parameters


Agent resolution

The endpoint resolves the target agent using the first applicable path: 1. Explicit agentId query parameter The endpoint looks up the agent by its agentId string, verifies it exists, and verifies it is owned by the calling external application. Returns 403 Forbidden if the agent belongs to a different app. 2. X-Forge-User-JWT header (no agentId) Resolves the Forge user from the JWT, then looks up the PERSONAL agent for the (calling-app, user) pair. Returns 400 if no personal agent has been provisioned for this user — call findOrCreateAgent first.
Read-only: no JIT provisioning. Unlike findOrCreateAgent, this endpoint does not provision a user or personal agent as a side effect. If the user has never been seen by Forge, it returns 404 Not Found. If the user exists but has no personal agent for this app, it returns 400. GET endpoints must not have write side effects.
3. App default agent (no agentId, no JWT) If neither an explicit agentId nor a user JWT is provided, the endpoint falls back to the external application’s defaultAgentId. Returns 400 if no default agent is configured for the app.

Response

The response uses the OpenAI-compatible model list envelope — not the standard Forge { data, meta } management envelope.

200 OK

Not the Forge management envelope. This endpoint returns the OpenAI-compatible shape directly — no wrapping { data, meta }. This is intentional: the response can be parsed by any OpenAI-compatible model picker with no adaptation.

Errors


Example


See also

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

X-Forge-User-JWT
string

Your user's identity token, signed by your app's identity provider. Forge provisions the user on first sight and acts for them; without it, name a user already provisioned that way (userId).

Query Parameters

agentId
string

An agent the calling app owns.

Response

The agent's models

object
enum<string>
required
Available options:
list
data
object[]
required