This page documents both. They follow the OpenAI URL convention so SDKs work against either with a base-URL swap and nothing else.
External App inference carve-out: /api/inference/v1/*
Why it’s preserved
When the legacy/api/v1/* management surface was retired, the inference paths were deliberately kept. The reasoning: the OpenAI/Anthropic-compatible SDK ecosystem hardcodes /v1/chat/completions-style paths, and breaking that breaks every consumer that mounts Forge as an OpenAI base URL.
The v1 in /api/inference/v1/* is a third-party convention, not the Forge management API version. The two version namespaces are independent:
- Forge management API is at
/api/v3/*(and the/api/v2/*compatibility surface) and evolves under Forge’s own versioning policy. /api/inference/v1/*mirrors the OpenAI URL shape and changes only when the upstream OpenAI surface changes.
Endpoints
Both mounts resolve to the same handler instance, so both grant types behave identically and the two paths cannot drift. The JWKS used to verify the minted JWT is likewise served at both
GET /.well-known/jwks.json and GET /api/inference/v1/.well-known/jwks.json. Prefer the root paths — they are what every quickstart and SDK example teaches.
Compatibility
Most OpenAI and Anthropic SDKs work out of the box if you point their base URL athttps://api.forge.gloo.com/api/inference/v1 and supply a Forge-issued bearer token.
Uploading a file for knowledge
An app adds a file to its knowledge in three calls:POST /api/inference/v1/fileswith{ "filename": "...", "mime_type": "..." }answers201with{ "file_id", "upload_url" }.POSTthe file’s raw bytes toupload_url. It answers200with{ "storageId" }. The URL carries a single-use token, so send noAuthorizationheader to it and do not share it. It accepts one upload of 1 to 20,971,520 bytes (20 MiB) within an hour of thePOST /filescall. A larger body answers413payload_too_large, an empty body400empty_upload, a second upload409upload_already_received, an upload after the hour403upload_url_expired, and a URL that matches no pending file403invalid_upload_url. Like the other file routes, it answers401app_not_activewhen the app is no longer active and503governance_door_stoppedwhile theapi_keysdoor is stopped.POST /api/inference/v1/files/confirmwith{ "file_id", "storage_id" }, wherestorage_idis thestorageIdthe upload answered. The file moves toprocessing.
storage_id answers 400 storage_id_mismatch with a sentence ending Reference: <id>., and the same id in decision_id. The refusal is recorded as a decision, and the file stays pending_upload.
Access control
Every/api/inference/v1/* route an app token calls — chat completions, the agent card and the inference file routes (/files, /files/confirm, /files/get, /files/delete) — requires the inference:use permission. The token must carry the inference:app scope, and the app must hold inference:use through its role grants; chat completions and the agent card answer a token without the scope with 401 (wrong_scope), and every route answers 403 (missing_permission) when the app’s roles, narrowed by the token’s scopes, lack the permission. A token carrying only files:read or files:write therefore gets 403 on the inference file routes. See Permissions and scopes.
While Forge is stopped
When a person stops Forge in the Console (the global kill switch),/chat/completions and the inference file writes (POST /files, the upload to upload_url, POST /files/confirm, DELETE /files/delete) answer 403 with code platform_killed and the fixed message “Forge is stopped by an operator. A person resumes it in the Console.” Chat completions refuse after the token’s own scope and permission checks (which keep their 401/403 answers) and before any user is resolved or provisioned or any model runs; the file writes refuse before any upload URL, row or deletion. The operator’s reason is never returned. File reads (GET /files, /files/get) keep working. Retry after a person resumes Forge.
The /chat/completions endpoint then enforces two further levels of access control sourced from the calling External App’s configuration:
Agent gate — allowAllAgents
By default (allowAllAgents: false), an External App may only use agents listed in its allowedAgentIds. When allowAllAgents: true the app can address any active agent.
Model gate — allowAllModels
Each agent carries an externalModelAllowlist — the set of model IDs external callers may request through that agent. When a request specifies a model not in the list, the endpoint returns:
allowAllModels: true on the External App row (via PATCH /api/v3/external-apps/{externalAppId}) to bypass this check for that app — the caller may then request any model string and Forge will route it directly. The agent’s own externalModelAllowlist is still respected for apps without this flag; allowAllModels defaults to false (safest).
Both flags are managed through the External Apps management API.
Not part of the management API
Operations in this section are NOT covered by the v2 OpenAPI spec — they follow the OpenAI shape, not Forge’s REST-RPC envelope. In particular:- No
data/metaenvelope. Responses use OpenAI’s native shape (choices,usage, etc.). - Streaming uses SSE in OpenAI’s format, not Forge’s management envelope.
- Errors keep OpenAI’s structure,
error.{ message, type, param, code }, so an OpenAI SDK reads them. Each also carrieserror.docUrlandmeta.requestIdfrom Forge’s error envelope, with the id in theX-Request-Idheader.
LLM proxy: /api/llm/v1/*
The LLM proxy is a separate OpenAI-compatible surface used by platform-internal callers — Forge’s own agent turns, procedure sandboxes, and any future caller that wants Forge to act as a tier-routed LLM gateway rather than a transparent passthrough. It’s distinct from the External App carve-out: the auth model, the access-control model, and the routing semantics all differ.
Endpoints
Virtual keys
Virtual keys are minted server-side and bound to a calling principal (worker, factory, etc.). The token is opaque from the caller’s perspective; Forge resolves it to avirtualKeyId server-side, enforces the principal’s quotas and policies, and attributes the resulting token spend back through the token spend attribution chain.
Because the proxy is a platform-internal surface, virtual keys are not externally provisioned — they are minted by the dispatch path that needs them. Operators who want a long-lived OpenAI-compatible inference URL for a third-party SDK should use the External App carve-out instead.
See also: LLM routing tier abstraction | External Apps | Models

