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 local endpoint that conifer serve opens speaks the same wires, so a client written against one works against the other.
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. |
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.