REST API

All API endpoints live under https://api.kiomon.com (or your own deployment’s URL). Authenticate with a Kiomon API key unless noted:

Authorization: Bearer <api-key>

Public routes (no auth): GET / (health), POST /api/auth/* (Better Auth sign-in / OAuth callbacks), and the billing webhook.

Documents — /api/documents

Method & path	Purpose
POST /	Ingest a document (used by the extension and connectors). Validates your plan’s limits first.
GET /check	Dry-run check whether an ingest is allowed (before you send it).
GET /	List documents: paginated, filterable by workspace, tag, source, kind.
GET /:id	Fetch a document (metadata + body).
PATCH /:id	Update title, excerpt, body, tags. Updates are re-indexed automatically
DELETE /:id	Delete one document.
DELETE /bulk	Bulk delete: { "ids": [...] }.
POST /:id/archive	Soft-hide from retrieval and lists (recoverable).
POST /:id/restore	Bring an archived document back.
POST /:id/forget	Permanent purge from storage and search.
POST /:id/rate	Rate a document/memory: `{ “rating”: 1
POST /:id/approve	Approve a pending memory draft → active memory.
POST /:id/reject	Reject a pending draft → archived.
GET /:id/links	Link suggestions: pending/completed with scores and statuses.
POST /:id/link	Manually link two documents.
DELETE /:id/links/:targetId	Unlink.

Memories — /api/memories

Method & path	Purpose
POST /batch-draft	Agent-facing: writes 1–25 learnings as pending_approval drafts (workspace_id, learnings[] with kind/title/body + optional metadata). Not retrievable until approved.
GET /	List memories (kind filters, pagination).

Search — /api/search

GET /api/search?q=<query>&limit=<n>&workspace_id=<ws>&kind=<kind>

Hybrid keyword + semantic search with cleansed queries, AND→OR fallback, and prefix matching. Rate-limited per plan.

Chat & conversations — /api/rag

Method & path	Purpose
POST /ask	Grounded Q&A (streaming). Loads conversation history, retrieves citations, streams the answer + sources.
GET /sources	Recent retrieval sources/citations.
GET /conversations	List conversations.
GET /conversations/:id	Get a conversation with its message history.
PATCH /conversations/:id	Rename / update a conversation.
DELETE /conversations/:id	Delete a conversation.

Agent — /api/agent/chat

POST /api/agent/chat — the tool-using agent (SSE stream). Event shapes:

data: {"type":"tool","tool":{"name":"search_knowledge_base","status":"call","detail":{...}}}
data: {"type":"delta","text":"…"}
data: {"type":"sources","sources":[...]}
data: {"type":"saved","conversation":{...}}
data: {"type":"error","message":"…"}

Graph — /api/graph

GET /api/graph — nodes and edges for a workspace (includes link statuses and scores).

Workspaces — /api/workspaces

Method & path	Purpose
GET /	List workspaces.
POST /	Create (plan-gated: 2 free / 20 pro).
PATCH /:id	Rename.
DELETE /:id	Delete workspace + contents.
GET /:id/context	Pre-flight context pack (pinned, routines, topic facts, stats) — the same shape the MCP get_workspace_context returns.

Connectors — /api/connectors

Connectors are Pro-only. POST /, POST /:id/sync, GET /:id/confluence/spaces, and POST /connections/:id/google/token return 402 { code: "pro_required", needsUpgrade: true } on a Free billing entity. GET / stays readable and reports locked so the dashboard can render the gate.

Method & path	Purpose
GET /	List connectors ({ connectors, locked }).
POST /	Create (OAuth flow starter; Pro-only).
GET /connections	List the user’s OAuth connections.
DELETE /connections/:id	Disconnect (revokes access).
PATCH /:id	Update sync config (spaces, folders, label).
DELETE /:id	Remove a connector.
GET /:id/confluence/spaces	List Confluence spaces for selection (Pro-only).
POST /:id/sync	Trigger a manual sync run (Pro-only).
POST /connections/:id/google/token	Mint a short-lived Drive token for the picker (Pro-only).

Account — /api/user

Method & path	Purpose
GET /settings	Read your settings.
PATCH /settings	Update settings.
PATCH /profile	Update profile.
POST /avatar	Upload a new avatar.
DELETE /account	Delete your account (cleans up all your data).
GET /usage	Live usage counters (documents, storage, API calls).
GET /stats	Aggregate statistics.
GET /stats/historical	Historical metrics for the Insights page.

API keys — /api/keys

Method & path	Purpose
GET /	List keys (id, prefix, label, tier, created at).
POST /	Generate a key. Returns the full key once (plan-gated: 1 free / 10 pro).
DELETE /:id	Revoke (immediate for holders).

Billing — /api/billing

Method & path	Purpose
POST /webhooks/dodo	Public. Payment provider webhook, signature-verified.
GET /subscription	Current plan, status, period end.
POST /sync	Re-sync subscription state.
POST /checkout	Create a hosted checkout session.
POST /verify	Server-side verification of a checkout return.
POST /portal	Open the customer billing portal.
POST /portal-sync	Refresh state after returning from the portal.

OpenAI-compatible — /v1

Method & path	Purpose
GET /v1/models	kiomon-rag, kiomon-embed.
POST /v1/chat/completions	Grounded chat (stream + non-stream, citations). Rate-limited per key/plan.
POST /v1/embeddings	Embed text using Kiomon’s semantic embedding model.

Auth — /api/auth/*

Better Auth endpoints (sign-in, sign-up, OAuth callbacks, sessions). The dashboard’s auth client talks to these directly.

Error conventions

• 400 — invalid request (validation message included)
• 401 — missing/invalid credentials
• 402 — plan limit reached (e.g. key cap, document cap)
• 404 — not found
• 429 — rate limit exceeded (with a message)

Error bodies use { "error": "message" }.