API Reference
This page carries everything the endpoints have in common: the base URL, authentication, the parameters several of them take, the response envelope, streaming, the errors the gateway returns and the limits it applies. Each endpoint page below keeps only what is specific to it and links back here for the rest.
Base URL
https://api.bricksum.com/v1Every path below is relative to this base URL. The Anthropic SDKs append /v1 themselves, so point them at https://api.bricksum.com instead.
Authentication
Send your API key in the Authorization header as a Bearer token. The x-api-key header is read only when Authorization is absent: when both are present, Authorization is used, and an Authorization value that is not a Bearer token is rejected with no fallback to x-api-key. A request with no usable key is rejected with 401 before it reaches the endpoint.
The gateway does not read the anthropic-version and anthropic-beta headers, so a request is handled the same way with or without them, and a query string such as ?beta=true is accepted. GET /key is the one exception to the rule above: it is served by the Kiln API, takes the key as a Bearer token only, and its page says so. Authentication
Endpoints
The endpoints served today. Pick one by the format your client already speaks; the gateway meters them all the same way.
| Endpoint | Format | Streaming | Use it for |
|---|---|---|---|
| POST/chat/completions | OpenAI | data: chunks | Conversations and tool calling. The endpoint most OpenAI clients reach for. |
| POST/completions | OpenAI | data: chunks | Text that continues a prompt. No conversation, no tool calling. |
| POST/responses | OpenAI | typed events | The Responses format, used by Codex CLI. Stateless: send the whole conversation in input each time. |
| POST/messages | Anthropic | typed events | The Anthropic Messages format, used by Claude Code. Translated to chat completions and metered the same way. |
| POST/messages/count_tokens | Anthropic | no | The input token count of a Messages request. Runs no inference and is not billed. |
| GET/models | OpenAI | no | The model IDs the gateway can serve right now. Not billed. |
| GET/key | Kiln | no | Project, status, spend limit, expiry and spend of the key that makes the call. Served by the Kiln API, not by the gateway. |
Common request parameters
These are the request parameters several endpoints take. They are documented here once; an endpoint page lists the name and says only what it does differently.
Support status
- supported
- The gateway handles it, or a published measurement shows it works.
- passed through
- Forwarded to the model server; not verified by Kiln.
- ignored
- Accepted with 200, but not applied. The rest of the response is normal.
- not supported
- Rejected with an error, or not working on the models named in the description.
modelstringsupportedModel ID, for example qwen3-32b. GET /models lists the IDs you can send. An ID that is not in the catalog is rejected before the request reaches the model: the OpenAI-shaped endpoints answer 404 (model_not_found), the Anthropic-shaped ones 404 (not_found_error).
messagesarrayrequiredsupportedThe conversation so far, oldest message first. An empty or missing array is rejected with 400 and is not billed. A message carries a role and its content; which content shapes a message can take differs between the OpenAI-shaped and the Anthropic-shaped endpoints, so each endpoint page lists its own.
max_tokensintegersupportedMaximum number of tokens to generate. Reasoning tokens count toward it, so set it generously. What happens at the cap, and what happens when the field is missing, differs per endpoint.
streambooleansupportedWhen true, the response is a stream of server-sent events instead of one JSON body. Send a JSON boolean. The OpenAI-shaped endpoints send data: lines and end the stream with data: [DONE]; the Anthropic-shaped Messages endpoint sends typed events.
- Default
- false
toolsarraysupportedDefinitions of the functions the model can call. Each one needs a name, a description and a JSON Schema of its arguments; the field names differ between the two formats. Which models apply which tool choice mode is listed in the capability table on the Models page.
tool_choicestring | objectsupportedWhether the model has to call a tool. With automatic tool choice the model decides. Forced tool choice is not applied on every model; which models apply which mode is in the capability table on the Models page. On qwen3-32b (measured 2026-09-26), forced tool choice fails without a clear error: tool_choice "required" returns HTTP 500 with a plain-text "Internal Server Error" body, and naming a function returns 200 with empty arguments (finish_reason "stop"). Neither is a 4xx, so do not retry it — send tool_choice "auto" only.
Which of these an endpoint takes, and whether it is required there, is on that endpoint's page. Parameters that are not listed on an endpoint page are forwarded to the model server as sent; Kiln has not verified them.
Response envelope
A successful request answers 200 with a JSON body in the format of the endpoint. Two things are the same across the metered endpoints:
| Field | Type | Description |
|---|---|---|
| usage | object | Token counts for the request. The field names follow the format of the endpoint, and each endpoint page lists them. usage.cost, the amount in USD deducted from credits, is added by the gateway to the OpenAI-shaped JSON responses and to the final stream chunk of a Chat completions or Completions stream. The Responses stream events and the Messages response carry token counts without a cost field. |
| X-Neocloud-Generation-Id | header | Response header with the ID of the usage event for this request. Store it with your logs. The endpoints that run no inference — GET /models and POST /messages/count_tokens — publish no usage event and send no such header. |
Streaming
With stream: true the response is a stream of server-sent events. The OpenAI-shaped endpoints send one data: line per chunk and end with data: [DONE]; Responses and Messages send typed events, each an event: line followed by its data: line. Either way the connection stays open until the generation ends, which is how a long request avoids the timeout below. The chunk fields and the event types are on each endpoint page. Streaming
Errors the gateway returns
These come from the gateway before the request reaches the endpoint, so they look the same on every endpoint it fronts. Branch on the HTTP status, not on the message text. Errors an endpoint raises itself — a rejected payload, an unknown model ID, a wrong method — are on its own page, and the full list of status codes is on the Errors page. Errors
| Status | Cause | What to do |
|---|---|---|
| 401 | The API key is missing, malformed, unknown or expired. | Check the x-api-key or Authorization header and the key's expiry. |
| 402 | Credits are exhausted, the organization reached its monthly budget, or the key reached its spend limit. | Top up, or ask an admin to raise the budget or the limit. |
| 403 | The API key is suspended or revoked. | Reactivate the key in the console, or create a new one. |
| 429 | The organization exceeded its requests/min or tokens/min limit. | Wait x-ratelimit-reset seconds, then retry. |
Limits
- Context length: set per model, prompt and output combined. The Models page lists each model's value. A longer request is rejected with 400.
- Request body: the gateway reads at most the first 8 MiB. Keep the body smaller than that.
- Timeouts: the gateway ends a request after 60 minutes. A non-streaming request sends no bytes until it completes, and the network edge can cut such a connection after about 100 seconds. Send long generations with stream: true.
- Rate limits per organization: 60 requests/min by default, a tokens/min limit if one is set, and 8 concurrent requests.
Headers and retry guidance for 429 are on the Rate limits page.
The current serving stack does not apply every OpenAI parameter. Each endpoint page marks its own parameters with a support status, and the gaps are collected in one place on Migrating from OpenAI.