Pre-launch. Early access only: payments and public sign-up open after commercial and legal sign-off.

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' }],
});

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>
claude

ANTHROPIC_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

  1. Open Cursor Settings → Models.
  2. Enter your KolayAPI key as the OpenAI API key.
  3. Turn on Override OpenAI Base URL and set it to https://api.kolayapi.com/v1.
  4. Add a model id from GET /v1/models as 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.

Error codes
CodeHTTPMeaning
authentication_error401The key is missing, malformed, revoked or expired.
permission_error403The key is not allowed from this IP address, or the account is restricted.
model_not_allowed403The key has a model allowlist that does not include this model.
not_commercially_authorized403The model is not available to this account and key.
account_suspended403The organization is suspended or closed.
entity_not_available403API access is not available for this account yet, or the billing profile is incomplete.
invalid_request_error400The body is invalid. The message names the first offending field, for example max_tokens.
unsupported_feature400The model does not support a requested feature, or the request would have no verified cost bound. The detail field feature names it.
not_found_error404The model does not exist.
model_retired410The model was retired. The detail field replacement suggests a successor when one exists.
insufficient_budget_for_bound402The request may cost more than the available balance or the key limit allows. Lower max_tokens or add credit.
rate_limit_error429The key reached its requests per minute, tokens per minute or concurrency limit.
retry_later503A temporary condition (busy account, upstream unavailable, price not ready). Retry shortly.
gateway_not_live503Inference is not enabled on this environment.
api_error500Unexpected server error.
overloaded_error529The 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.