Kunkun Docs

Type-safe HTTP client for Kunkun's local API server — search, ask, and manage RAG knowledge bases from external applications.

@kunkunsh/client is a published npm package for external applications to access Kunkun's local API server over HTTP. It works in Node.js, browser, Deno, and Bun.

npm install @kunkunsh/client

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

const client = createKunkunClient({
  baseUrl: "http://localhost:9559",  // default port
  apiKey: "kk-xxxx",                  // create in Settings → API Keys
});

Don't have an API key yet? See Local API Server — enable the server and create a token with the permissions you need.

API overview

RAG

// List and get instances
client.rag.instances.list()
client.rag.instances.get(instanceId)

// Search and ask
client.rag.search(instanceId, { query, topK?, mode?, threshold?, filters? })
client.rag.ask(instanceId, { question, maxContextChunks?, citations? })

// Stream answer (SSE)
const stream = client.rag.askStream(instanceId, { question })
for await (const event of stream) { /* metadata | text_delta | done | error */ }

// Manage items
client.rag.items.list(instanceId)
client.rag.items.create(instanceId, { type, path|title|url|content })
client.rag.items.reindex(instanceId, itemId)
client.rag.items.delete(instanceId, itemId)
client.rag.items.update(instanceId, itemId, { title?, content? })

// Update settings
client.rag.settings.patch(instanceId, { name?, chunkSize?, searchMode?, ... })

File Search

client.fileSearch.roots()
client.fileSearch.status()
client.fileSearch.search({ query, limit?, extensions?, includeHidden? })

Types

All DTOs are exported from @kunkunsh/client:

import type {
  PublicRagInstance, PublicRagItem, PublicRagItemData,
  RagSearchInput, RagSearchResult,
  RagAskInput, RagAskResult,
  SseRagEvent,
  CreateRagItemInput,
  FileSearchInput, FileSearchResult, FileSearchRoot,
} from "@kunkunsh/client";

Error handling

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

try { /* call */ }
catch (error) {
  if (error instanceof KunkunApiError) {
    console.error(error.code, error.status, error.body);
  }
}

Error codes include HTTP_401 (missing/invalid key), FORBIDDEN (key lacks permissions), NOT_FOUND, INVALID_REQUEST, and INTERNAL_ERROR.

Subpath exports

Import	Provides
`@kunkunsh/client`	Full client + types
`@kunkunsh/client/contract`	Hono route contracts for server-side use
`@kunkunsh/client/rag`	RAG client only (no valibot dependency)
`@kunkunsh/client/rag/contract`	RAG route contracts only
`@kunkunsh/client/file-search`	File search client only
`@kunkunsh/client/file-search/contract`	File search route contracts only

Server-side contracts

Hosts implementing the Kunkun API can import the route contracts to get validated, OpenAPI-annotated routes:

import { createKunkunApiRoutes, type KunkunApiHandlers } from "@kunkunsh/client/contract";
import { Hono } from "hono";

const app = new Hono().route("/api/v1", createKunkunApiRoutes(handlers));

The contract package defines the KunkunApiHandlers interface that server-side code must implement:

interface KunkunApiHandlers {
  rag: RagApiHandlers;
  fileSearch: FileSearchApiHandlers;
}

Custom fetch

Pass a custom fetch implementation for proxies, timeouts, or environments without globalThis.fetch:

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

REST API reference

The server exposes an OpenAPI 3.0 spec and interactive API reference:

URL	Description
`/openapi.json`	OpenAPI spec (machine)
`/scalar`	Scalar API reference UI (human)

Kunkun Client