API
The endpoint contract
What you can build against and count on: the wires the gateway serves, the receipt on every response, and the rule that nothing you rely on is taken away.
This is the contract for api.conifer.build.
The wires
| Path | Wire | Specified by |
|---|---|---|
/v1/chat/completions | OpenAI chat completions, plus /v1/models for the list | OpenAI's API, served as is |
/v1/responses | OpenAI Responses, the wire Codex uses | OpenAI's API, served as is |
/v1/messages | Anthropic Messages, plus count_tokens | Anthropic's Messages API, served as is |
Contract version 5.0.0. The request and response bodies are the providers’ own. Everything Conifer adds travels in x-conifer-* headers, never in the body, so your client library needs no changes.
It only grows
That rule is quoted from the contract itself. A header, field or error code you build against today will be there tomorrow. New ones may appear, and a client may ignore anything it does not recognize. An unknown header or field is never an error.
The ask and the receipt
You name a model. The gateway serves it. The response says what ran and what it cost.
The ask
| Model field | Meaning |
|---|---|
<model-id> | Serve this model, or refuse with a typed error. A named model is never quietly swapped for another. |
A retry is safe. Send the same idempotency-key header on the retry and the turn is billed once.
The receipt
Every completed response carries these headers.
| Header | Meaning |
|---|---|
x-conifer-requested-model | The model you asked for. |
x-conifer-effective-model | The model that answered. |
x-conifer-endpoint | Who was billed: credits for your Conifer balance, or byok:<provider> when your own provider key paid. |
x-conifer-cost-nanousd | What the call cost, in billionths of a dollar. Absent on a streamed response, where the headers go out before the cost is known. Absent never means free. |
x-conifer-list-cost-nanousd | On a byok:<provider> call only: a list-rate estimate of what the provider bills your own key, in billionths of a dollar. A discounted provider contract bills less. Conifer charges none of it. Absent when the catalog does not price the model. On a stream it arrives as list_cost_nanousd on the final conifer_receipt event when you send x-conifer-stream-receipt: true. |
The header family only grows. A later version may add headers and will not remove or rename these.
Every route, parameter and error is in the API reference. How the cost is metered is on Billing & caching.