Skip to content
quebragalho/docs

API reference

Responses

POST/v1/responses

The OpenAI Responses format, with and without streaming. It is the route for Codex, in the terminal and the app, with the same API key and the same balance as chat.

One block in config.toml

Paste the block into ~/.codex/config.toml. The same file works for Codex in the terminal and for the Codex app.

config.toml
# ~/.codex/config.tomlmodel = "glm-5.3-flash"model_provider = "quebragalho"[model_providers.quebragalho]name = "Quebra-Galho"base_url = "https://api.quebragalho.dev/v1"env_key = "QUEBRAGALHO_API_KEY"wire_api = "responses"
  • wire_api = "responses" and a base ending in /v1 are required.
  • The key lives in the QUEBRAGALHO_API_KEY variable. The app reads the variables from your shell profile (for example ~/.zshenv): export it there and reopen the app.
  • Since 0.134, a profile is a file of its own, ~/.codex/<name>.config.toml, used with codex --profile <name>.
  • The warning about a model without metadata is expected for ids Codex does not know. It carries on with default values.
  • In the app, each new conversation's title comes from a separate request, currently to gpt-6-luna, billed at its price.

gpt-* ids: recent Codex versions replace these models' tools with a mode of their own (code mode), and here tool calls still fail now and then. For tasks with tools, prefer ids from other families for now.

Direct call

Without Codex, the route accepts the OpenAI Responses API body. The key goes in Authorization: Bearer.

cURL
curl https://api.quebragalho.dev/v1/responses \  -H "Authorization: Bearer $QUEBRAGALHO_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "glm-5.3-flash",    "input": "explain RAG in 3 lines"  }'

In the OpenAI SDK, it is client.responses.create with the base at https://api.quebragalho.dev/v1.

What differs from OpenAI

Under the hood, the request becomes the same chat request. Almost everything carries over. What does not:

  • Function tools work. Provider-hosted tools, such as web search, are ignored.
  • max_output_tokens above your plan's cap returns 400.

Errors

In the OpenAI format, with the codes Codex uses to decide whether to stop or retry.

SituationResponseWhat the client does
Insufficient balance429 insufficient_quotaCodex stops. It would retry a 402.
Conversation longer than the context400 context_length_exceededRecognizes the full context and compacts.
Missing or invalid key401 invalid_api_keyStops.
Per-minute or concurrency limit429 rate_limit_errorWaits for Retry-After.
Provider failure or slowness5xx api_errorRetries on its own.

502 and 504 responses arrive as 503: Cloudflare, in front of the API, swaps those statuses. Read the type and the code in the body, not just the status.