Runtime Routes

Codex Pooler keeps runtime traffic, operator metadata, browser pages, health checks, and metrics on separate route families. This page covers the public runtime and operator API surfaces only. It is a reference for choosing the right base URL, not an exhaustive Phoenix route dump.

Quick map

Route family	Use it for	Auth boundary
/backend-api/codex	Codex backend compatibility route for Codex-compatible clients	Pool API key bearer auth
/backend-api	Backend file bridge, audio transcription, and backend usage routes	Pool API key bearer auth
/v1	Narrow OpenAI-compatible /v1 support for selected SDK routes	Pool API key bearer auth
/mcp	Read-only operator MCP endpoint for metadata lookup	Operator-owned MCP bearer token
Usage routes	Runtime usage checks exposed on compatibility paths	Pool API key bearer auth

A Pool API key represents a Pool. It doesn’t represent one upstream account. Codex Pooler uses the Pool policy, model support, limits, health, routing state, and session continuity to select an eligible upstream account for each supported runtime request.

Backend API routes

Use the backend API when a client expects Codex backend semantics. The main base URL is:

https://pooler.example.com/backend-api/codex

Supported Codex backend compatibility routes include:

Route	Meaning
GET /backend-api/codex/models	List backend models visible to the authenticated Pool
POST /backend-api/codex/responses	Send backend Responses requests through Pool routing and accounting
GET /backend-api/codex/responses	Backend websocket response-stream compatibility
POST /backend-api/codex/responses/compact	Backend compact compatibility
/backend-api/codex/v1/*	Explicit backend aliases for clients that use /backend-api/codex/v1 as a base URL
POST /backend-api/codex/images/generations	Backend image generation proxy route
POST /backend-api/codex/images/edits	Backend image edit proxy route

The /backend-api/codex/* surface is explicit authenticated Codex backend compatibility. It isn’t a wildcard proxy and it isn’t the OpenAI SDK surface.

Backend control-plane routes

Codex Pooler also exposes exact authenticated backend control-plane proxy routes under /backend-api/codex. These routes forward to exact upstream control-plane paths and keep request logs metadata-only.

Public examples include:

Route	Meaning
GET /backend-api/codex/thread/goal/get	Backend thread-goal lookup compatibility
POST /backend-api/codex/thread/goal/get	Backend thread-goal lookup compatibility with JSON body
POST /backend-api/codex/thread/goal/set	Backend thread-goal update compatibility
POST /backend-api/codex/thread/goal/clear	Backend thread-goal clear compatibility
POST /backend-api/codex/analytics-events/events	Backend analytics event proxy route
POST /backend-api/codex/memories/trace_summarize	Backend memory trace summary proxy route
POST /backend-api/codex/alpha/search	Backend alpha search proxy route
POST /backend-api/codex/safety/arc	Backend safety proxy route
GET /backend-api/codex/agent-identities/jwks	Backend agent identity JWKS route

POST /backend-api/codex/realtime/calls is a Codex backend control-plane SDP proxy route only. It is not OpenAI Realtime SDK compatibility.

Backend files, audio, and usage

The /backend-api family also includes backend routes that don’t live under /backend-api/codex:

Route	Meaning
POST /backend-api/files	Create upstream-backed file metadata and return an upstream upload URL
POST /backend-api/files/:file_id/uploaded	Finalize an upstream-backed file upload
POST /backend-api/transcribe	Backend audio transcription compatibility
GET /backend-api/wham/usage	Backend usage route
GET /api/codex/usage	Usage route
GET /wham/usage	Usage route
GET /backend-api/wham/agent-identities/jwks	Backend WHAM agent identity JWKS route

The backend file bridge stores metadata only. File bytes stay upstream-backed.

OpenAI-compatible /v1 routes

Use /v1 when a client or SDK needs an OpenAI-shaped base URL:

https://pooler.example.com/v1

Codex Pooler provides narrow OpenAI-compatible /v1 support for selected SDK routes. Supported requests are translated into Codex-compatible work, then sent through the same Pool routing, limit checks, account selection, and accounting path as backend traffic. It doesn’t provide full OpenAI API parity.

Supported /v1 routes include:

Route	Meaning
GET /v1/models	List models visible to the authenticated Pool
POST /v1/responses	OpenAI-shaped Responses request compatibility
GET /v1/responses	Narrow Responses websocket compatibility only
POST /v1/responses/compact	Compact compatibility
POST /v1/chat/completions	Chat Completions compatibility
GET /v1/usage	Usage route
GET /v1/files	File metadata listing
POST /v1/files	File metadata create route
GET /v1/files/:file_id	File metadata lookup
GET /v1/files/:file_id/content	Deterministic unsupported content read after ownership checks
DELETE /v1/files/:file_id	Deterministic unsupported delete after ownership checks
POST /v1/audio/transcriptions	Audio transcription compatibility
POST /v1/images/generations	Image generation compatibility
POST /v1/images/edits	Image edit compatibility

GET /v1/responses is narrow Responses websocket compatibility. It is not /v1/realtime support.

Unsupported /v1 boundary

Unsupported /v1 routes return deterministic OpenAI-shaped unsupported endpoint errors when explicitly routed. They don’t enter gateway dispatch.

Unsupported public routes include:

Route	Boundary
POST /v1/images/variations	Unsupported endpoint
POST /v1/embeddings	Unsupported endpoint
POST /v1/batches	Unsupported endpoint
POST /v1/moderations	Unsupported endpoint
POST /v1/fine_tuning/jobs	Unsupported endpoint
GET /v1/responses/:response_id	Unsupported endpoint
POST /v1/responses/:response_id/cancel	Unsupported endpoint
DELETE /v1/responses/:response_id	Unsupported endpoint
/v1/realtime	Unsupported Realtime SDK route family

OpenAI Realtime SDK websocket and session routes are not supported.

MCP endpoint

The operator MCP endpoint is rooted at /mcp, not under /backend-api or /v1.

Route	Meaning
POST /mcp	JSON-RPC Streamable HTTP endpoint
GET /mcp	Routed endpoint, but stateless SSE is unavailable today
OPTIONS /mcp	Allowed MCP methods response

MCP uses operator-owned bearer MCP tokens. It doesn’t accept Pool API keys, browser sessions, cookies, query tokens, invite tokens, upstream tokens, or custom headers as authentication.

MCP output is metadata-only and scoped by the operator’s owner or assigned-Pool visibility. It is an operator inspection endpoint, not a runtime client endpoint.