The KoboldCpp API: one server, many compatible endpoints

Pick your path

• Connect SillyTavernThe most common question: the URL, the API type and what to select.
• Use an OpenAI SDK or an OpenAI-style appBase URL, chat, streaming and what is supported.
• The KoboldAI native APIGenerate, stream, count tokens, check the model.
• Janitor AI, Open WebUI, VS Code, n8nOther apps and how to point them at KoboldCpp.
• Use it from a phone or the internetLAN address, tunnels, HTTPS and passwords.
• Share it with othersAI Horde, parallel requests and admin mode.

Your KoboldCpp API URL

The API and the web page share one address. By default that is http://localhost:5001: the host is your own PC and the port is set by --port (default 5001) F05. Lite opens at that address in a browser F31.

The address changes when you change the port, when the app runs on another device (use the PC’s LAN address instead of localhost, see remote access), when you use a tunnel (an https:// address with no port, see tunnels), and on Colab or a cloud GPU, which give you their own address.

Do you need an API key?

No, unless you started KoboldCpp with --password. Then the password is the key, and clients send it as Authorization: Bearer <key>. You can also set it with the KCPP_PASSWORD environment variable. --adminpassword is a different password, for admin functions such as model switching. We tested a server started with a password F25:

The password protects generation, not discovery: the web page and /api/v1/model stay reachable without the key, and /api/v1/model then hides the model name (koboldcpp/protected-model). /v1/models still shows the real name, even for a wrong key F72. KoboldCpp’s help says image endpoints are not protected; we have not tested that. If an app insists on a key and you set no password, users report that any text works; we have not tested it.

Which API should I use?

Check your server

With the model loaded, open the address in a browser on the same PC: the Lite page should appear. Then ask for the version and the model from a terminal:

$ curl http://localhost:5001/api/extra/version
$ curl http://localhost:5001/api/v1/model
$ curl http://localhost:5001/v1/models

If those answer, the server is up and any failure is in the app’s settings. Or check from the browser:

The full tester also builds requests and lists the settings for the clients we connected.

Every endpoint

All 100 routes from KoboldCpp’s own code, with our status. “Works” means we called it and got a 200 on 1.124.2 (F23); everything else is untested by us. Filter by family or search.

Notes from the source: OpenAI-style paths are also served without the /v1 prefix (for example /chat/completions); most handlers match on the end of the path, so /lcpp/... reaches the same handlers; and in router mode (--routermode) a proxy sits in front.

Streaming

There is no server switch for streaming: the client asks for it with each request. KoboldCpp streams as server-sent events in two shapes F23:

data: {"token": " three, four, five,", "finish_reason": null}1data: {"token": "", "finish_reason": "length"}2

data: {"id": "chatcmpl-A3023341", "object": "chat.completion.chunk", "created": 1794574088, "model": "koboldcpp/qwen2.5-0.5b-instruct-q4_k_m", "choices": [{"ind…1data: [DONE]2

Lite has its own streaming toggle: Lite settings.

Gotchas we found

1. Two version numbers. /api/v1/info/version answers 1.2.5, the version of the KoboldAI API KoboldCpp emulates. KoboldCpp’s own version is at /api/extra/version: 1.124.2 F24.
2. /api/extra/version lists what is loaded. It reports which features are available, as captured on a text-only server F24:

version

1.124.2

protected

false

llm

true

txt2img

false

vision

false

transcribe

false

tts

false

embeddings

false

jinja

false

mcp

false

parallelrequests

1

With a vision, Whisper and embeddings model loaded, the same call reported vision, transcribe and embeddings as true F27. 3. Embeddings without a model succeed with nothing. /v1/embeddings returned 200 with an empty vector and "model": "inactive": check the vector length F24. 4. There is no /swagger.json. It returns 404. The spec is at /api?json=1 F23. 5. A password hides the model name on one route only. With --password, /api/v1/model shows koboldcpp/protected-model F25, but /v1/models still lists the real model F72. 6. Ollama’s version call is documented in the source as returning an emulated Ollama version, and /slots as always answering 501. We have not tested either.

Common URL mistakes

One request at a time: the queue

By default KoboldCpp answers one request at a time and queues the rest F26. --parallelrequests 2 lets two run together. On the CI runner that gave no gain: two simultaneous requests took 1.69 s and 3.15 s by default, and 3.28 s each with two slots. On our Linux test machine it did help: one request took 3.4 s and four simultaneous requests all finished in 6.2 s F75. Test it on your own setup before relying on it.

The queue holds 10 waiting requests by default (--queuelimit), a request times out after 600 seconds (--reqtimeout), and a request body can be up to 32 MB (--maxrequestsize). We have not measured a GPU.

The built-in API docs

KoboldCpp serves its own interactive documentation at /api on your server, an interactive Swagger page titled “KoboldCpp API” that groups the OpenAI-compatible and Anthropic endpoints as the recommended ones for beginners F32.

Close

This page adds what the Swagger page lacks: tested responses, how the password behaves, the common mistakes and the status of each route.