Documentation
KolayAPI speaks two protocols on one host, https://api.kolayapi.com. Use your KolayAPI key anywhere you would use an Anthropic or OpenAI key.
Pre-launchPublic launch is pending. Model identifiers below are written as <model-id>: use the ids thatGET /v1/models returns for your key. The catalog lists only models we are authorized to resell.
API keys
Sign in to the dashboard, open your organization and create a key underAPI keys. Keys look like kapi_sk_live_<key id>_<secret>. The full key is shownonce: store it in a secret manager. Rotate or revoke it at any time.
Authenticate with x-api-key: <key> or Authorization: Bearer <key>. Both work on every endpoint.
Anthropic protocol: POST /v1/messages
curl https://api.kolayapi.com/v1/messages \
-H "x-api-key: $KOLAYAPI_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "<model-id>",
"max_tokens": 256,
"messages": [{"role": "user", "content": "Hello"}]
}'With the Anthropic SDK, only the base URL and key change:
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
apiKey: process.env.KOLAYAPI_KEY,
baseURL: 'https://api.kolayapi.com', // the SDK appends /v1/messages
});
const msg = await client.messages.create({
model: '<model-id>',
max_tokens: 256,
messages: [{ role: 'user', content: 'Hello' }],
});max_tokensis required, as in the Anthropic API.POST /v1/messages/count_tokensis not supported: KolayAPI does not return token estimates, and answers400 unsupported_feature.- Errors come back in Anthropic's shape:
{"type":"error","error":{"type":…,"message":…},"request_id":…}.
OpenAI protocol: POST /v1/chat/completions
curl https://api.kolayapi.com/v1/chat/completions \
-H "Authorization: Bearer $KOLAYAPI_KEY" \
-H "content-type: application/json" \
-d '{
"model": "<model-id>",
"messages": [{"role": "user", "content": "Hello"}]
}'from openai import OpenAI
client = OpenAI(
api_key=os.environ["KOLAYAPI_KEY"],
base_url="https://api.kolayapi.com/v1", # the SDK appends /chat/completions
)
reply = client.chat.completions.create(
model="<model-id>",
messages=[{"role": "user", "content": "Hello"}],
)Errors come back in OpenAI's shape: {"error":{"message":…,"type":…,"code":…,"param":…}}.
Models: GET /v1/models
curl https://api.kolayapi.com/v1/models -H "Authorization: Bearer $KOLAYAPI_KEY"The list contains only the models this key may call. Send anthropic-version to get an Anthropic-shaped list, or omit it for the OpenAI shape. GET /v1/models/<id> returns one model, or404 if it does not exist.
Streaming
Set "stream": true on either endpoint to receive server-sent events in that protocol's native format.
curl -N https://api.kolayapi.com/v1/messages \
-H "x-api-key: $KOLAYAPI_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "<model-id>",
"max_tokens": 256,
"stream": true,
"messages": [{"role": "user", "content": "Hello"}]
}'curl -N https://api.kolayapi.com/v1/chat/completions \
-H "Authorization: Bearer $KOLAYAPI_KEY" \
-H "content-type: application/json" \
-d '{
"model": "<model-id>",
"stream": true,
"stream_options": {"include_usage": true},
"messages": [{"role": "user", "content": "Hello"}]
}'If a stream fails after it has started, the error arrives as an error event (Anthropic) or a finaldata: chunk (OpenAI), because the HTTP status was already sent. You are billed for what was actually used. If your client disconnects mid-stream, the request is settled from the provider's usage record.
Claude Code
Point Claude Code at KolayAPI with two environment variables:
export ANTHROPIC_BASE_URL=https://api.kolayapi.com
export ANTHROPIC_AUTH_TOKEN=kapi_sk_live_<key id>_<secret>
claudeANTHROPIC_API_KEY works in place of ANTHROPIC_AUTH_TOKEN. Create a separate key with thecoding agent use case for each developer or machine, so you can cap and revoke them individually.
Agent compatibility is verified per model and per agent. A model is advertised as agent-compatible only after it passes that agent's test suite, so pick a model the catalog marks as such.
Cursor
- Open Cursor Settings → Models.
- Enter your KolayAPI key as the OpenAI API key.
- Turn on Override OpenAI Base URL and set it to
https://api.kolayapi.com/v1. - Add a model id from
GET /v1/modelsas a custom model, and select it.
Menu labels can change between Cursor versions; what matters is an OpenAI-compatible base URL ending in /v1and a KolayAPI key. Use a key with the coding agent use case.
Budgets and limits
Every key has its own controls, set when you create it in the dashboard. All are optional:
- Daily limit
- Maximum credits the key may spend per day.
- Monthly limit
- Maximum credits the key may spend per month.
- Total limit
- Lifetime credit cap for the key.
- IP allowlist
- IPv4 or IPv6 addresses and CIDR ranges. Empty means any IP. Other addresses get
403. - Use case
- API for your own code, or Coding agent for Claude Code and Cursor.
Credits are spent from your organization's prepaid wallet; key limits only cap how much of it one key can use. 1 credit equals USD 1 of upstream list cost.
How a request is checked
Before a request goes upstream, KolayAPI reserves the most it could cost (the model's price applied to your input and max_tokens). The reservation must fit inside your available balance and inside the key's daily, monthly and total limits, otherwise you get 402 insufficient_budget_for_bound with no upstream call. When the request finishes, the actual cost is charged, never more than the reservation, and the rest is released. A lowermax_tokens means a smaller reservation.
Errors
Errors use each protocol's native body. For Anthropic the error.type is the code below; for OpenAI it iserror.code (the OpenAI error.type is the nearest OpenAI class). Official SDKs choose retries from the HTTP status. Send the x-request-id response header to support when you need help.
| Code | HTTP | Meaning |
|---|---|---|
authentication_error | 401 | The key is missing, malformed, revoked or expired. |
permission_error | 403 | The key is not allowed from this IP address, or the account is restricted. |
model_not_allowed | 403 | The key has a model allowlist that does not include this model. |
not_commercially_authorized | 403 | The model is not available to this account and key. |
account_suspended | 403 | The organization is suspended or closed. |
entity_not_available | 403 | API access is not available for this account yet, or the billing profile is incomplete. |
invalid_request_error | 400 | The body is invalid. The message names the first offending field, for example max_tokens. |
unsupported_feature | 400 | The model does not support a requested feature, or the request would have no verified cost bound. The detail field feature names it. |
not_found_error | 404 | The model does not exist. |
model_retired | 410 | The model was retired. The detail field replacement suggests a successor when one exists. |
insufficient_budget_for_bound | 402 | The request may cost more than the available balance or the key limit allows. Lower max_tokens or add credit. |
rate_limit_error | 429 | The key reached its requests per minute, tokens per minute or concurrency limit. |
retry_later | 503 | A temporary condition (busy account, upstream unavailable, price not ready). Retry shortly. |
gateway_not_live | 503 | Inference is not enabled on this environment. |
api_error | 500 | Unexpected server error. |
overloaded_error | 529 | The service is overloaded. |
For Anthropic clients some codes map to the closest Anthropic type: model_not_allowed usespermission_error, and gateway_not_live uses api_error.