External API

ollmo exposes API-key authenticated external endpoints for programmatic access to knowledge bases, search, and chat.

Authentication

All external API requests must carry the X-API-Key header:

curl -H "X-API-Key: <your-api-key>" \
  http://localhost:8080/api/v1/external/knowledge-bases

API keys are created and revoked in the web UI under Settings → API Keys.

Endpoints

Base path: /api/v1/external

Method	Path	Description
GET	/knowledge-bases	List knowledge bases
POST	/knowledge-bases	Create a knowledge base
GET	/knowledge-bases/:kbId	Knowledge base details
PUT	/knowledge-bases/:kbId	Update a knowledge base
DELETE	/knowledge-bases/:kbId	Delete a knowledge base
GET	/knowledge-bases/:kbId/documents	List documents
POST	/knowledge-bases/:kbId/documents	Upload a document
POST	/knowledge-bases/:kbId/search	Hybrid search
GET	/conversations	List conversations
POST	/conversations/:id/messages/stream	Streaming chat (SSE)

Example: search

curl -X POST http://localhost:8080/api/v1/external/knowledge-bases/<kbId>/search \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "What file formats does ollmo support?", "top_k": 5}'

Example: streaming chat

curl -N -X POST http://localhost:8080/api/v1/external/conversations/<id>/messages/stream \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"content": "hello"}'

The response is an SSE event stream, returning tokens incrementally.