understudydocs

gateway api

Proxy endpoints

The gateway speaks both major API shapes at one host. Request and response bodies are the providers' own formats — these docs only describe what Understudy adds around them.

Endpoint summary

endpointshapenotes
POST /v1/messagesAnthropic MessagesStreaming and non-streaming. BYO or managed.
POST /v1/chat/completionsOpenAI Chat CompletionsStreaming and non-streaming. BYO or managed. Catalog models are requested here by id.
POST /v1/responsesOpenAI ResponsesNative Codex passthrough in managed mode. The selected model is forwarded unchanged.
POST /v1/responses/compactOpenAI Responses compactionNative Codex compaction passthrough in managed mode.
POST /v1/messages/count_tokensAnthropic token countingCompatibility shim, proxied to Anthropic.
GET /v1/modelsOpenAI model listThe public model catalog — ids your key can request in managed mode.
GET /healthz—Public liveness probe. No auth.

Compatibility contract

In passthrough, bodies forward unmodified and responses return unmodified — your SDK cannot tell the gateway is there beyond the extra response headers. When a request is routed, the gateway rewrites body.model to the serving model; the original value is preserved in the capture envelope as requested_model, and the served one is reported on x-understudy-effective-model.

GET /v1/models

request
curl https://api.understudylabs.com/v1/models \
  -H "Authorization: Bearer $UNDERSTUDY_API_KEY"
response (OpenAI list shape)
{
  "object": "list",
  "data": [
    {
      "id": "glm-5.1",
      "object": "model",
      "created": 1764892800,
      "owned_by": "understudy",
      "display_name": "GLM 5.1"
    }
  ]
}

Catalog ids are public names — they carry no provider, endpoint, or deployment details. Understudy resolves the serving provider behind each id and may change it without the id changing.

Use Codex through Understudy

Create an Understudy API key, project, and workload. Export the key asUNDERSTUDY_API_KEY, then add this provider to ~/.codex/config.toml and restart Codex.

~/.codex/config.toml
model_provider = "understudy"

[model_providers.understudy]
name = "OpenAI"
base_url = "https://api.understudylabs.com/v1"
env_key = "UNDERSTUDY_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
http_headers = { "x-understudy-project" = "<project-slug>", "x-understudy-workload" = "<workload-name>" }

Choose a model normally in Codex; Understudy does not rewrite it on these endpoints. The API key selects the organization, while the two headers select the project and workload used for traces, usage, and cost attribution. Responses currently supports managed credentials, not BYO provider keys.