HTTP API Reference

The complete API reference — all endpoints, request/response schemas, error codes, and a ready-to-use cURL example per route — is available at /api/. It is generated automatically from openapi.yaml in the repository, so it is always as current as the code it was written against.

This page only adds what a schema reference naturally doesn’t show: auth, streaming, and one end-to-end example.

Auth

curl http://127.0.0.1:2330/v1/health \
  -H "Authorization: Bearer $OLLAMA_AGENT_TOKEN"

The header is only needed if api.auth_token is set in config.json (or OLLAMA_AGENT_TOKEN in the Docker container). Without a configured token, the API is open — sensible only behind 127.0.0.1 or your own reverse proxy.

Streaming (Server-Sent Events)

POST /v1/agent/run and POST /v1/chat return a text/event-stream instead of a single JSON response when "stream": true is set:

curl -N -X POST http://127.0.0.1:2330/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"input": "Erkläre den Endpoint-Pool in zwei Sätzen.", "stream": true}'

event: delta
data: {"text":"Der Endpoint-Pool"}

event: delta
data: {"text":" verteilt Anfragen über"}

event: result
data: {"session_id":"a1b2c3","title":"Endpoint-Pool erklärt","output":"Der Endpoint-Pool verteilt Anfragen über mehrere Ollama-Server ...", ...}

Zero or more delta events with text chunks, followed by exactly one result (the complete result, including session_id/title/context for /v1/chat) or error.

One end-to-end example: create, continue, and compact a session

BASE=http://127.0.0.1:2330

# 1. First message — creates a new session
SID=$(curl -s -X POST $BASE/v1/chat \
  -d '{"input": "Was ist ein Endpoint-Pool?"}' | jq -r .session_id)

# 2. Follow-up message in the same session
curl -s -X POST $BASE/v1/chat \
  -d "{\"input\": \"Und was passiert bei einem Ausfall?\", \"session_id\": \"$SID\"}" | jq .output

# 3. Check context fill level
curl -s $BASE/v1/sessions/$SID | jq .context

# 4. Compact if needed (summarize history via LLM)
curl -s -X POST $BASE/v1/sessions/$SID/compact | jq .context

More examples — for each individual endpoint, with the respective fields and error responses — directly in the API reference.