REST API

The KaaS backend exposes a REST API at the configured listen address (default http://localhost:8080). All endpoints use JSON request/response bodies unless noted otherwise.

Base URL

http://<host>:<port>/api

---

Content Submission

POST /api/submit

Submit text content for compilation into the knowledge base.

• Content-Type: application/json
• Body limit: 10 MiB

Field	Type	Description
content	string	Raw text to compile
source_url	string	(optional) URL source for the content

Response: 201 Created — returns the created task object.

---

POST /api/submit/files

Upload one or more files for compilation. Uses multipart/form-data.

• Content-Type: multipart/form-data

Field	Type	Description
files	file(s)	One or more files to upload

File size and count limits are controlled by the upload configuration (see GET /api/upload/config).

Response: 201 Created — returns the created task object(s).

---

GET /api/upload/config

Get the current upload limits.

Response: 200 OK

{
  "max_file_size": 10485760,
  "max_files": 10,
  "allowed_extensions": [".md", ".txt", ".pdf"]
}

---

Task Management

GET /api/tasks

List compilation tasks. Supports pagination.

Query Param	Type	Description	Default
page	int	Page number	1
page_size	int	Items per page	20
status	string	Filter by status	—

Response: 200 OK — returns a paginated task list.

---

GET /api/tasks/{id}

Get a single task by ID.

Path Param	Type	Description
id	string	Task ID

Response: 200 OK — returns the task object.

Error: 404 Not Found — task does not exist.

---

GET /api/tasks/{id}/content

Get the source content of a task (the original submitted text or file content).

Path Param	Type	Description
id	string	Task ID

Response: 200 OK — returns the task content.

Error: 404 Not Found — task does not exist.

---

DELETE /api/tasks/{id}

Delete a task and its associated data.

Path Param	Type	Description
id	string	Task ID

Response: 204 No Content

Error: 404 Not Found — task does not exist.

---

Wiki

GET /api/wiki

List all wiki articles as a tree structure.

Response: 200 OK — returns the wiki tree (directories and files).

---

GET /api/wiki/file

Get the content of a single wiki file.

Query Param	Type	Description
path	string	Relative path to the wiki file

Response: 200 OK — returns the file content (Markdown).

Error: 404 Not Found — file does not exist.

---

Chat

POST /api/chat

Start a streaming chat session against the compiled wiki. The response is an SSE (Server-Sent Events) stream.

• Content-Type: application/json
• Response Content-Type: text/event-stream

Field	Type	Description
query	string	The user's question
session_id	string	(optional) Session ID for conversation history
model	string	(optional) Model override

SSE event types:

Event type	Description
status	Processing status update (e.g. "retrieving", "generating")
delta	Incremental answer text chunk
done	Final event with metadata (sources, cost)
error	Error occurred during processing

---

Session Management

GET /api/sessions

List all chat sessions, ordered by most recently updated.

Response: 200 OK — returns an array of session objects.

---

POST /api/sessions

Create a new chat session.

• Content-Type: application/json

Field	Type	Description
title	string	(optional) Session title

Response: 201 Created — returns the created session object.

---

PATCH /api/sessions/{id}

Update a session (e.g. rename).

Path Param	Type	Description
id	string	Session ID

Field	Type	Description
title	string	New session title

Response: 200 OK — returns the updated session object.

---

DELETE /api/sessions/{id}

Delete a session and all its messages.

Path Param	Type	Description
id	string	Session ID

Response: 204 No Content

---

GET /api/sessions/{id}/messages

List messages in a session.

Path Param	Type	Description
id	string	Session ID

Response: 200 OK — returns an array of message objects.

---

Health Check

GET /healthz

Liveness probe for container orchestration. Does not touch the store or AI engine.

Response: 200 OK

{"status": "ok"}

---

MCP Endpoint

/mcp

The MCP (Model Context Protocol) streamable-http endpoint. Only available when [ai.mcp] enabled = true in configuration (or KAAS_MCP_ENABLED=true).

• Authentication: Bearer token when KAAS_MCP_TOKEN is set.
• Protocol: MCP streamable-http transport

See MCP Server for the tool specification.