Kunkun Docs

Kunkun runs a local HTTP server that exposes RAG search, file search, and other features over a typed REST API. The server binds to 127.0.0.1 only — it never listens on the network.

Enabling the server

Open Settings → API Keys

Press Cmd+, (macOS) or Ctrl+, (Windows/Linux) and navigate to the API Keys section.

Enable the server

Toggle Enable Local API Server. The default port is 9559. You can change it if there's a conflict.

The server starts automatically with Kunkun. You can stop and restart it from the same settings page.

Create an API key

Click Create API Key, give it a name, and select which services it can access:

Service	Actions	Description
RAG	`search`, `ask`	Search and ask questions against knowledge bases
RAG	`admin`	Full access including item management and settings
File Search	`search`	Search indexed files

Treat API keys like passwords — they grant access to your indexed data. The admin action allows creating, updating, and deleting knowledge base items. Scope keys to the minimum actions needed.

Copy the key immediately — you won't be able to see it again.

Using the REST API

The server exposes endpoints under /api/v1. All requests require Authorization: Bearer <api-key>.

Health check

curl http://localhost:9559/
# → { "status": "ok", "name": "kunkun-desktop" }

List knowledge bases

curl -H "Authorization: Bearer kk-xxxx" \
  http://localhost:9559/api/v1/rag/instances

Search a knowledge base

curl -X POST \
  -H "Authorization: Bearer kk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "query": "what is Kunkun", "topK": 5, "mode": "hybrid" }' \
  http://localhost:9559/api/v1/rag/instances/<instanceId>/search

Ask a question

curl -X POST \
  -H "Authorization: Bearer kk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "question": "What does the architecture documentation say?" }' \
  http://localhost:9559/api/v1/rag/instances/<instanceId>/ask

Stream an answer (SSE)

curl -N -X POST \
  -H "Authorization: Bearer kk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Explain the permission model." }' \
  http://localhost:9559/api/v1/rag/instances/<instanceId>/ask/stream
# event: metadata
# event: text_delta
# event: done

List items in a knowledge base

curl -H "Authorization: Bearer kk-xxxx" \
  http://localhost:9559/api/v1/rag/instances/<instanceId>/items

OpenAPI spec

The server serves an OpenAPI 3.0 specification and a Scalar API reference UI:

URL	Description
`/openapi.json`	OpenAPI 3.0 spec (machine-readable)
`/scalar`	Interactive API reference (human-readable)

Using the TypeScript client

npm install @kunkunsh/client

import { createKunkunClient } from "@kunkunsh/client";

const client = createKunkunClient({
  baseUrl: "http://localhost:9559",
  apiKey: "kk-xxxx",
});

// List instances
const instances = await client.rag.instances.list();

// Search
const results = await client.rag.search(instances[0].id, {
  query: "Kunkun architecture",
  topK: 5,
});

See the full API reference in the developer documentation — all methods, types, error handling, and streaming support.

Security

The server binds to 127.0.0.1 only — not accessible from other devices
All requests require a Bearer token validated server-side
Tokens are hashed before storage — Kunkun never stores raw tokens
API keys can be scoped to specific services and actions
Expired tokens are rejected automatically

Managing tokens

From Settings → API Keys you can:

View all active tokens (name, prefix, creation date, expiry)
Revoke tokens at any time
See the last used timestamp for each token

Local API Server

On this page