Skip to content
KOLDOS
Sign in
KOLDOS
Documentation menu
/

Examples and SDKs

Getting started

Local API

The REST API KOLDOS serves on your own computer.

Start it with koldos serve. It listens on 127.0.0.1:8128 by default, so nothing outside your computer can reach it. The Brain inspector uses port 8129 and never touches the API.

Start the local API
koldos serve

Authentication

An access token is optional. When one is set in the KOLDOS configuration, every /v1 request needs Authorization: Bearer <token>, except /v1/health, so a monitor can check the service without holding the credential.

Endpoints

MethodPathPurpose
GET/v1/healthModel, context window and cache type. Open even when a token is set.
GET/v1/modelsLists the model, served as "koldos".
POST/v1/chat/completionsA full KOLDOS turn in the common chat completions format, with optional streaming.
POST/v1/turnsA turn with the KOLDOS-specific result, including route and trace.
GET/v1/capabilitiesWhat this build implements, including vision availability.
POST/v1/attachmentsAttach files to the next turn. They are copied into the workspace.
GET/v1/chatsSaved conversations. Also POST, GET by id and DELETE.
GET/v1/workspaceThe project folder KOLDOS works in. POST changes it.
GET/v1/project/treeThe file tree of the workspace.

Use it from any compatible client

Point a client that speaks the common chat completions format at http://127.0.0.1:8128/v1 and use the model koldos. Editor extensions, scripts and bots then get the whole KOLDOS turn: routing, tools and verification, not just the model.

Target

Runs on your computer with koldos serve. This request works today against a running KOLDOS.

Sent as the user message. KOLDOS runs one turn for it.

temperature, max_tokens, top_p are accepted and ignored. KOLDOS sets its own budgets for every turn.

Generated request · local API
curl http://127.0.0.1:8128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "koldos",
    "messages": [
      {
        "role": "user",
        "content": "Explain what the function main does in src/app.py."
      }
    ]
  }'

This page never sends requests or asks for a key. Run the snippet from your own environment.

Errors

  • 400 when the request has no user message.
  • 401 when a token is set and the request does not carry it.
  • 413 when the message is longer than the configured limit.
  • 429 when the turn runs out of its budget.