API Reference

Kolbo Code exposes an OpenAI-compatible HTTP API at https://api.kolbo.ai/api/kolbo/v1. You can call it directly with any OpenAI SDK, curl, or your own HTTP client — the Kolbo Code CLI uses exactly these endpoints under the hood.

Authentication

Every protected endpoint accepts either header format:

X-API-Key: kolbo_live_xxxxx

or

Authorization: Bearer kolbo_live_xxxxx

Create an API key at app.kolbo.ai. See Authentication for the full device-code login flow that Kolbo Code uses on your behalf.

Endpoints

GET /api/kolbo/v1/balance

Returns the authenticated user's credit balance. Used by the CLI to display remaining credits before an expensive operation.

Request

curl https://api.kolbo.ai/api/kolbo/v1/balance \
  -H "X-API-Key: kolbo_live_xxxxx"

Response

{
  "available": 8340,
  "reserved": 0,
  "total": 8340
}

Errors

POST /api/kolbo/v1/files

Upload a file for use as an attachment in a subsequent chat/completions call. Returns a file descriptor you reference by id or url in the chat request.

Rate limited separately from chat (60 requests/minute per user).

Request

Multipart form-data with a single field named file:

curl -X POST https://api.kolbo.ai/api/kolbo/v1/files \
  -H "X-API-Key: kolbo_live_xxxxx" \
  -F "file=@./screenshot.png"

Limits

Automatic optimization

The server optimizes certain media types on the way in to keep chat turns fast and storage cheap:

• Images (image/*) — resized to 8K max dimension, re-encoded as JPEG at 82% quality, capped at 10 MB. PNGs with transparency may be preserved when optimization can't beat the original.
• Audio (audio/*) — transcoded to MP3 128 kbps / 44.1 kHz.
• Everything else — uploaded as-is.

The filename and mime_type in the response reflect the final stored file, not the original.

Response

{
  "id": "file_64f8a21c1d2e3f4a5b6c7d8e",
  "object": "file",
  "filename": "screenshot.jpg",
  "bytes": 184320,
  "mime_type": "image/jpeg",
  "url": "https://media.kolbo.ai/kolbo-code/<user_id>/2026-04-11/9f2c3d-screenshot.jpg",
  "created": 1775912345,
  "expires_at": 1775998745,
  "deduplicated": false
}

Errors

Using the file in a chat completion

Pass the url (or the full descriptor) as message content in /chat/completions. Vision-capable models will see the image directly:

{
  "model": "kolbo-cli",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What's in this screenshot?" },
        { "type": "image_url", "image_url": { "url": "https://media.kolbo.ai/kolbo-code/..." } }
      ]
    }
  ]
}

Audio files work the same way via audio_url content parts on audio-capable models.

GET /api/kolbo/v1/models

Lists the chat models available to Kolbo Code with pricing and capability metadata. No authentication required — the CLI uses this to populate its model picker before login.

Response (abbreviated)

{
  "object": "list",
  "data": [
    {
      "id": "kolbo-cli",
      "object": "model",
      "owned_by": "kolbo",
      "pricing": {
        "prompt": "...",
        "completion": "..."
      },
      "context_length": 200000,
      "supports_vision": true
    }
  ]
}

POST /api/kolbo/v1/chat/completions

OpenAI-compatible chat completions endpoint. Supports streaming (stream: true) and synchronous responses. See the OpenAI Chat Completions spec for the full request/response schema — Kolbo Code mirrors it.

Credit deduction happens on the completed request (streaming or not) against the paying user's balance. The amount is based on the chosen model's pricing and the final token usage returned by the provider.

Request

curl https://api.kolbo.ai/api/kolbo/v1/chat/completions \
  -H "X-API-Key: kolbo_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kolbo-cli",
    "messages": [{"role": "user", "content": "Write a haiku about tomatoes"}],
    "stream": false
  }'

Related

• Authentication — how to log in with kolbo auth
• Commands — the kolbo CLI command reference