Built-in interfaces

One of the biggest advantages of Klisk is that every agent you create comes with three ready-to-use interfaces out of the box — no frontend code needed. Just run klisk start and you get a full-screen chatbot, a REST API, and an embeddable widget, all pointing to the same agent.

klisk start my-agent --port 8080

That single command gives you:

Interface	URL	Use case
Full-screen chatbot	https://your-url/	Standalone chat app for end users
REST API	https://your-url/api/chat	Connect from any backend, mobile app, or automation
Embeddable widget	https://your-url/widget.js	Add a chat bubble to any existing website

All three share the same agent, tools, and configuration. No duplication.

---

Full-screen chatbot

Visit the root URL (/) and you get a complete chat application ready for end users.

Features:

• Message bubbles with full markdown rendering (bold, italic, code blocks, lists, tables, links)
• Tool call display — collapsible panels showing which tools the agent is using, with a spinner while running
• Thinking traces — see the agent's reasoning process (collapsible)
• File attachments — drag-and-drop or paperclip button to send images and PDFs
• Dark/light theme toggle (preference saved in localStorage)
• Reset button to start a new conversation

Embed mode

If you want to embed the full chatbot inside an iframe on your own site (instead of using the widget), append ?embed=1 to remove borders and padding:

<iframe
  src="https://your-url/?embed=1"
  style="width: 100%; height: 600px; border: none; border-radius: 12px;"
></iframe>

This is useful when you want the full chat experience (not just a floating bubble) integrated into a specific section of your page.

---

REST API

The API lets you connect your agent to anything: a mobile app, a backend service, a Slack bot, a Zapier automation, etc.

Send a message

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

Response:

{
  "response": "Hello! How can I help you today?",
  "state": {"previous_response_id": "resp_abc123"},
  "done": true
}

Conversation continuity

Pass the state object back in your next request to maintain context:

curl -X POST https://your-url/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "message": "Tell me more",
    "stream": false,
    "state": {"previous_response_id": "resp_abc123"}
  }'

Streaming

Set "stream": true to receive Server-Sent Events (SSE) in real time — useful for showing the response as it's being generated:

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

Events you'll receive:

Event	Description
token	A chunk of text from the agent
thinking	A chunk of the agent's reasoning
tool_call	The agent is calling a tool
tool_result	A tool returned a result
done	The response is complete (includes final text + state)
error	Something went wrong

Send images or PDFs

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 encoded content>"
      }
    ]
  }'

WebSocket

For real-time bidirectional communication, use the WebSocket endpoint:

wss://your-url/ws/chat?key=YOUR_KEY

Send messages as JSON:

{"message": "Hello"}

The server responds with the same event types as SSE (token, thinking, tool_call, tool_result, done, error).

For more details, see the Server API reference.

---

Embeddable widget

Add a floating chat bubble to any website with a single line of HTML:

<script src="https://your-url/widget.js"></script>

That's it. A chat button appears in the bottom-right corner. When clicked, it opens a chat panel connected to your agent.

Customization

<script
  src="https://your-url/widget.js"
  data-position="bottom-right"
  data-color="#2563eb"
  data-width="380px"
  data-height="560px"
  data-key="your-api-key"
></script>

Attribute	Default	Description
data-position	"bottom-right"	"bottom-right" or "bottom-left"
data-color	"#2563eb"	Button and header color (any CSS color)
data-width	"380px"	Chat panel width
data-height	"560px"	Chat panel height
data-key	—	API key for authentication

Examples

Green widget on the left:

<script
  src="https://your-url/widget.js"
  data-position="bottom-left"
  data-color="#10b981"
></script>

Larger widget with auth:

<script
  src="https://your-url/widget.js"
  data-width="450px"
  data-height="700px"
  data-key="your-widget-key"
></script>

The widget includes the same features as the full-screen chatbot: markdown, tool calls, thinking traces, file attachments, and theming.

For the full reference, see the Widget reference.

---

Protecting your interfaces

All three interfaces support API key authentication. Add keys to your .env:

KLISK_API_KEY=general-key          # Protects all interfaces
KLISK_CHAT_KEY=chat-key            # Only the chatbot
KLISK_WIDGET_KEY=widget-key        # Only the widget

Each interface handles auth differently:

• Chatbot — prompts the user for a key on first visit (saved in localStorage)
• API — requires Authorization: Bearer <key> header
• Widget — key passed via data-key attribute (transparent to the user)

See the Authentication reference for details.

---

Choosing the right interface

Scenario	Interface
Give end users a standalone chat app	Full-screen chatbot
Add AI chat to your existing website	Widget
Connect from a mobile app or backend	REST API
Build a custom chat UI	REST API or WebSocket
Embed in a specific page section	Chatbot with ?embed=1
Real-time bidirectional communication	WebSocket