Production server API

When you run klisk start, Klisk starts a production server with a REST API, WebSocket, and chat UI.

klisk start my-agent --port 8080 --host 0.0.0.0

Endpoints

Method	Path	Auth	Description
GET	/	No	Chat UI (SPA with markdown, tool calls, themes)
GET	/api/info	No	Agent info + auth status
GET	/health	No	Health check
POST	/api/chat	Yes*	Chat (SSE streaming or JSON)
WS	/ws/chat	Yes*	WebSocket chat

*Auth only required if API keys are configured. See authentication.

REST API

GET /api/info

Returns basic information about the agent.

{"name": "MyAgent", "agent": "Assistant", "auth_required": true}

POST /api/chat

Send a message to the agent.

Request:

{"message": "Hello", "stream": true, "state": {}}

Field	Type	Description
message	string	The user message
stream	boolean	true for SSE streaming, false for JSON response
state	object	Pass back between requests for conversation continuity
attachments	array	Optional file attachments (see below)

Auth header: Authorization: Bearer <key>

Non-streaming response (stream: false):

{"response": "Hello! How can I help?", "state": {...}, "done": true}

Streaming response (stream: true): Returns Server-Sent Events (SSE).

Attachments format

{
  "type": "image",
  "name": "photo.jpg",
  "mime_type": "image/jpeg",
  "data": "<base64 encoded, no data URL prefix>"
}

• type: "image" or "file" (for PDFs)
• data: Raw base64 string (not a data:... URL)

Supported formats: JPEG, PNG, GIF, WebP (images), PDF (files). Max 20MB per file.

WebSocket

WS /ws/chat

Auth: ?key=<key> query parameter.

Send a message:

{"message": "Hello", "previous_response_id": "resp_xxx"}

Send a message with attachments:

{
  "message": "Describe this image",
  "attachments": [
    {"type": "image", "name": "photo.jpg", "mime_type": "image/jpeg", "data": "<base64>"}
  ]
}

Clear conversation:

{"type": "clear"}

Streaming events

Both SSE and WebSocket emit the same event types:

Event	Data	Description
token	string	Text delta from the LLM
thinking	string	Reasoning/thinking delta
tool_call	{"tool": "name", "arguments": "...", "status": "running"}	Tool invocation started
tool_result	{"output": "..."}	Tool execution result
done	string (final output)	Run completed
error	string	Error message

Conversation state

State is handled differently depending on the provider:

Provider	State format
OpenAI	{"previous_response_id": "resp_xxx"}
LiteLLM	{"conversation_history": [...]}

The state is returned in the done event and should be passed back in subsequent requests.

Usage examples

# Non-streaming
curl -X POST https://your-url/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"message": "Hello", "stream": false}'

# Streaming (SSE)
curl -X POST https://your-url/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"message": "Hello", "stream": true}'

# With conversation state
curl -X POST https://your-url/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"message": "Follow up", "stream": false, "state": {"previous_response_id": "resp_xxx"}}'

# With image attachment
curl -X POST https://your-url/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "message": "What is in this image?",
    "stream": false,
    "attachments": [
      {"type": "image", "name": "photo.jpg", "mime_type": "image/jpeg", "data": "<base64>"}
    ]
  }'

Chat UI features

The built-in chat UI at / includes:

• Markdown rendering (bold, italic, code, lists, headings, links, tables)
• Tool call display (collapsible, spinner while running)
• Thinking traces (collapsible)
• File attachments with drag-and-drop
• Dark/light theme toggle
• Reset button
• Embed mode: /?embed=1 (full viewport, no borders)

Provider support for attachments

Format	Supported providers
Images	OpenAI, Anthropic Claude 3+, Google Gemini, AWS Bedrock, Vertex AI, Ollama (LLaVA)
PDFs	OpenAI (gpt-4o+), Anthropic, Google Gemini, Bedrock, Vertex AI