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.
# ~/.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/v1are required.- The key lives in the
QUEBRAGALHO_API_KEYvariable. 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 withcodex --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 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_tokensabove your plan's cap returns 400.
Errors
In the OpenAI format, with the codes Codex uses to decide whether to stop or retry.
| Situation | Response | What the client does |
|---|---|---|
| Insufficient balance | 429 insufficient_quota | Codex stops. It would retry a 402. |
| Conversation longer than the context | 400 context_length_exceeded | Recognizes the full context and compacts. |
| Missing or invalid key | 401 invalid_api_key | Stops. |
| Per-minute or concurrency limit | 429 rate_limit_error | Waits for Retry-After. |
| Provider failure or slowness | 5xx api_error | Retries 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.