API reference

Credentials go in Authorization: Bearer or x-api-key. The Azure SDK’s api-key header is accepted too. The OpenAI routes sit under /v1; the Anthropic base URL is the host with no suffix.

curl https://api.conifer.build/v1/chat/completions \
  -H "Authorization: Bearer $CONIFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "three names for a build cache"}]
  }'

Models differ in what they support. Read caps on GET /v1/models before you send tools or images. Reasoning traces and cache details appear in a response only when the model produced them.

curl -s https://api.conifer.build/v1/models \
  -H "Authorization: Bearer $CONIFER_API_KEY" \
  | jq '.data[] | {id, caps, context_window, pricing}'

Routes#

Parameters#

Streaming#

stream: true returns SSE on the chat, Messages and Responses routes. Tokens arrive as the model produces them, /v1/responses included. A few providers hand back the whole answer at the end, in the same chunk shape.

A stream is never silent for more than 15 seconds. When the first frame is slow (routing, a slow first token, a failover), the gateway sends the 200 head with the identity receipt headers and then a : keep-alive SSE comment every 15 seconds until the answer flows. SSE parsers skip comments. A failure after that head arrives in band, in the route’s own grammar: data: {"error":{…}} then [DONE] on chat, event: error on Messages, and response.failed on Responses. The error object is the same one the buffered envelope carries.

The cost header is absent on a stream because the response starts before the cost is known. On /v1/messages the settled cost arrives as a final conifer_receipt event after message_stop. On the chat and Responses wires, send x-conifer-stream-receipt: true to get the same conifer_receipt event, with the settled cost_nanousd, at the end of the stream (before [DONE] on chat). It is not an OpenAI event type, and openai-node’s responses.stream() helper rejects unknown events, so read an opted-in Responses stream with raw event iteration. Without the opt-in, send stream_options.include_usage and price the final chunk’s usage from the catalog. A missing receipt event means the cost was not confirmed, never that it was zero.

Time bounds#

Each upstream call is bounded at 280 seconds. A stream is bounded by the same 280 seconds of upstream silence between frames, and the keep-alives above hold the connection open meanwhile.

A buffered answer that is still running at 285 seconds (a failover walk, or routing plus a slow model) is committed early so no proxy cuts it: the gateway sends 200 with x-conifer-keepalive: committed, then a space every 10 seconds, then the answer. That 200 is provisional. The body ends with one extra member, "conifer_receipt": {"status": …, "headers": {…}}, holding the real status and the receipt headers a fast answer would have carried. If the call fails without being charged, the connection is closed before the body ends, so your client sees a transport error and can retry with the same Idempotency-Key. A charged error ends normally, with its error status in conifer_receipt.status; do not retry it. For very long outputs, stream.

Finish reasons#

On the chat wire, stop and tool_calls are finished turns. length means the output or context budget ran out, and content_filter is a refusal. Two more values mark a turn that did not finish: pause_turn when the provider paused it, and incomplete for any other or missing stop. Partial tool calls are withheld on all of these. The choice may also carry provider_stop_reason (the provider’s own words) and provider_stop_details. The list can grow, so treat any value you do not recognise as unfinished, never as success. On /v1/responses the same outcomes are status: "incomplete" with incomplete_details.reason.

Receipt headers#

Every response carries a receipt in its headers. On a stream the identity headers are present and the cost header is absent, because the head is sent before the cost settles. On a response marked x-conifer-keepalive: committed the same headers travel in the body’s conifer_receipt.headers instead (see Time bounds). The full list is on Routing.

One header goes the other way. x-conifer-max-cost-nanousd sets a hard ceiling for the request. If it could cost more, Conifer refuses with a 402 before the model runs and nothing is charged.

Errors#

Reasoning traces#

On POST /v1/chat/completions, the trace is at choices[0].message.reasoning, the OpenRouter and OpenAI-compat name. Some models also set choices[0].message.reasoning_content, DeepSeek’s name. Both fields stream on choices[0].delta. Not every model emits either field. A missing field means there was no trace.

Two optional request fields control reasoning. Send reasoning as { effort | max_tokens }, or send reasoning_effort as one of none | minimal | low | medium | high | xhigh | max. One vocabulary covers every provider. Where a model offers fewer levels, Conifer maps yours to the nearest one it has. On Anthropic models the effort becomes a thinking budget, so set max_tokens high enough to leave room for the answer after the thinking.

curl https://api.conifer.build/v1/chat/completions \
  -H "Authorization: Bearer $CONIFER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 8192,
    "reasoning": {"effort": "medium"},
    "messages": [{"role": "user", "content": "three names for a build cache"}]
  }'

On POST /v1/messages, a thinking block is a content item with type: "thinking".

{
  "type": "thinking",
  "thinking": "the model scratch work",
  "signature": "…"
}

Prompt caching#

On the chat wire, cache counts appear under usage.prompt_tokens_details as cached_tokens and cache_write_tokens. Both are 0 when nothing was cached, and the details object itself may be absent. Usage reports only the fields that exist.

{
  "prompt_tokens_details": {
    "cached_tokens": 80,
    "cache_write_tokens": 0
  }
}

On /v1/messages, send cache_control breakpoints. Usage reports cache_read_input_tokens and cache_creation_input_tokens. Cached input is priced at the model’s cache-read rate, and the receipt reflects it.

curl https://api.conifer.build/v1/messages \
  -H "x-api-key: $CONIFER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 1024,
    "system": [{
      "type": "text",
      "text": "You are a build-cache namer. Keep answers to three words.",
      "cache_control": {"type": "ephemeral"}
    }],
    "messages": [{"role": "user", "content": "three names for a build cache"}]
  }'

{
  "input_tokens": 120,
  "cache_creation_input_tokens": 80,
  "cache_read_input_tokens": 0,
  "output_tokens": 24
}