External apps
List available models for an agent
Returns the OpenAI-compatible model list for a specific agent. Resolves by explicit agentId, user JWT, or app default. Requires permission agents:read.
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
/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. ExplicitagentId 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.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
- Find or create a personal agent — provision the agent before fetching its models
- Inference Carve-Out — send completions once you know the model
- External App API overview — auth and domain context

