API Reference

Cailos is an OpenAI-compatible AI gateway. Point any OpenAI SDK at it — everything just works.

Authentication

Every request requires an API key in the Authorization header:

Authorization: Bearer cai_your_key_here

Create keys in the dashboard (per-team). Keys are Argon2-hashed at rest — the full key is shown only once at creation.

Base URL

Set this as base_url in any OpenAI SDK. All paths below are relative to this.

Quickstart

Pythonfrom openai import OpenAI

client = OpenAI(
    base_url=,
    api_key="cai_your_key_here",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

cURLcurl /chat/completions \
  -H "Authorization: Bearer cai_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

List Models

Returns all available model codenames. Each codename may be backed by multiple providers — Cailos picks the best one based on your routing hints.

Requestcurl /models \
  -H "Authorization: Bearer cai_your_key_here"

Response{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet",
      "object": "model",
      "created": 0,
      "owned_by": "cailos"
    },
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 0,
      "owned_by": "cailos"
    }
  ]
}

Use these id values as the model parameter in chat completions.

Chat Completions

Send a conversation, get a completion. Fully compatible with the OpenAI Chat Completions API.

Request body

Messages

Standard OpenAI message format:

Routing & Codenames

The model field takes a codename — a standardised name like gpt-4o or claude-sonnet. The same codename can be served by multiple providers (e.g. llama-3.3-70b might be available from Groq, Together, and DeepInfra).

Cailos picks the best provider automatically. By default it optimises for quality (highest intelligence rating). You can change this with the cailos extension:

Example{
  "model": "llama-3.3-70b",
  "messages": [{ "role": "user", "content": "Hello" }],
  "cailos": {
    "optimise": "speed"
  }
}

Response Format

Standard OpenAI chat completion response:

200 OK{
  "id": "chatcmpl-8a3b2c1d4e5f...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

Tool call response

When the model invokes tools, finish_reason is "tool_calls" and the message includes a tool_calls array:

Tool calls{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\": \"Amsterdam\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

To continue the conversation, append the assistant message (with tool_calls) and a tool message (with the result) back into messages.

Errors

All errors follow the OpenAI error envelope:

{
  "error": {
    "message": "Model 'nonexistent' not found or not active.",
    "type": "not_found_error",
    "param": null,
    "code": null
  }
}

Rate Limits

Each API key has a configurable per-minute rate limit (set at creation). When exceeded, requests return 429.

• The window resets every 60 seconds.
• A rate limit of 0 means unlimited.
• Rate limiting is per-key, not per-team or per-model.

Supported Providers

You never interact with providers directly — just send a codename and Cailos handles format translation. For transparency, here's what's under the hood: