API reference

OpenAI compatibility

What the gateway supports, what it rejects and what it silently ignores, before you migrate.

On this page

Supported
Rejected with 400
Ignored
Not available
Differences in responses
Migration checklist

Cairva implements OpenAI-style text chat. Everything outside that is either rejected with an error or silently ignored, and it's better to know which before you migrate.

Supported

POST /v1/chat/completions with system, user and assistant messages
Message content as a string or an array of text parts
Streaming over server-sent events, with usage in the final chunk
max_tokens, max_completion_tokens, temperature, top_p, stop, user
GET /v1/models, scoped to your key
The OpenAI error envelope, and Retry-After on 429

Rejected with 400

Input	Result
Image, audio or file content parts	`validation_failed`
`tool`, `function` or `developer` roles	`validation_failed`
Assistant messages with `null` content, as produced by tool calls	`validation_failed`
More than 200 messages, or none	`validation_failed`
`max_tokens` above 32,768	`validation_failed`
More than 4 stop sequences	`validation_failed`

Ignored

These fields are accepted and dropped. Your request runs as if you hadn't sent them.

Field	What you get instead
`tools`, `tool_choice`, `functions`	No tool calls are ever returned
`n`	Always one choice
`response_format`	Plain text. Ask for JSON in the prompt and validate it yourself
`logprobs`, `top_logprobs`	No log probabilities
`seed`, `presence_penalty`, `frequency_penalty`, `logit_bias`	Not passed to the provider
`stream_options`	Usage is always sent in the last streamed chunk
Extra fields on messages, such as `name`	Dropped

Not available

Embeddings, images, audio, files, assistants, batches, the Responses API and the legacy completions endpoint. Only the four endpoints in the introduction exist.

Differences in responses

Every response has a cairva object. SDKs keep it as an extra field. See SDKs.
usage can be null when the provider didn't report counts. Code that reads usage.total_tokens without a check will throw.
Streamed deltas carry content only, with no initial role chunk.
model in the response is Cairva's model id, which is what you sent.
Reasoning isn't returned. See Output tokens you don't see.

Migration checklist

Change the base URL to https://cairva.xyz/v1 and the key to your Cairva key.
Set model to the id from /v1/models.
Remove tool calling and structured output, or handle them in your own code.
Guard every read of usage for null.
Set max_tokens deliberately, since it's held from your allowance.
Handle 402 and 403 allocation errors. They mean your agreement, not your code, needs attention.