Docs/API Reference

API Reference

Complete documentation of all KairosRoute API endpoints and schemas.

Authentication

All API requests require authentication using your API key. Include your key in the Authorization header.

curl https://kairosroute.com/v1/chat/completions \
  -H "Authorization: Bearer kr_live_xxxxx..."

Security: Never expose your API key in client-side code. Always use it server-side.

POST /v1/chat/completions

Creates a model response for the given chat conversation using intelligent routing.

Request Parameters

Parameter	Type	Description
`model`	string	Model to use. Use `kr-auto` for intelligent routing.
`messages`	array	A list of messages comprising the conversation so far.
`temperature`	number	What sampling temperature to use, between 0 and 2. Default: 1.
`max_tokens`	integer	The maximum number of tokens to generate in the response.
`stream`	boolean	If true, partial message deltas will be streamed. Default: false.

Example Request

curl https://kairosroute.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kr_live_..." \
  -d '{
    "model": "kr-auto",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Explain quantum computing in simple terms."
      }
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

Response

{
  "id": "chatcmpl-8HqZj...",
  "object": "chat.completion",
  "created": 1699564320,
  "model": "gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing is a revolutionary..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 45,
    "completion_tokens": 180,
    "total_tokens": 225
  }
}

Custom Response Headers

Header	Description
`X-KairosRoute-Provider`	Which model provider was used (e.g., "openai", "anthropic")
`X-KairosRoute-Cost`	Cost in USD for this request
`X-KairosRoute-Savings`	Amount saved in USD by using KairosRoute routing

Error Codes

Code	Message
`401`	Unauthorized - Invalid or missing API key
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Routing service unavailable
`503`	Service Unavailable - All models are currently unavailable

GET /v1/models

Lists the models available to use with the API.

Example Request

curl https://kairosroute.com/v1/models \
  -H "Authorization: Bearer kr_live_..."

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "kr-auto",
      "object": "model",
      "owned_by": "kairosroute",
      "permission": [],
      "root": "kr-auto",
      "parent": null
    },
    {
      "id": "gpt-4",
      "object": "model",
      "owned_by": "openai",
      "permission": [],
      "root": "gpt-4",
      "parent": null
    },
    {
      "id": "gpt-3.5-turbo",
      "object": "model",
      "owned_by": "openai",
      "permission": [],
      "root": "gpt-3.5-turbo",
      "parent": null
    },
    {
      "id": "claude-3-opus",
      "object": "model",
      "owned_by": "anthropic",
      "permission": [],
      "root": "claude-3-opus",
      "parent": null
    }
  ]
}

API Key Management

Manage your API keys through the dashboard or these endpoints.

POST /api/auth

Create a new API key

curl -X POST https://kairosroute.com/api/auth \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer kr_live_..." \
  -d '{
    "name": "Production Key",
    "expires_in": 7776000
  }'

GET /api/auth

List all your API keys

curl https://kairosroute.com/api/auth \
  -H "Authorization: Bearer kr_live_..."

DELETE /api/auth/:key_id

Revoke an API key

curl -X DELETE https://kairosroute.com/api/auth/key_123abc \
  -H "Authorization: Bearer kr_live_..."

Rate Limits

Free tier: 100 requests/minute
Pro tier: 1,000 requests/minute
Enterprise: Custom limits

When rate limited, you'll receive a 429 status code. Retry after the time specified in the Retry-After header.

← Quickstart Migration →