Documentation
Home GitHub

API Reference

Query KuraDB through its local, read-only Gin HTTP API.

Base URL

KuraDB binds to 127.0.0.1 and writes the selected URL to ~/.config/kuradb/endpoint.

BASE="$(cat ~/.config/kuradb/endpoint)"

All current routes use GET and are grouped under /api. There are no content mutation endpoints.

Endpoint summary

Method Path Purpose Status
GET /api/health Check process availability Current
GET /api/list Inspect registered and loaded databases Current
GET /api/search Run keyword search, semantic search, or both Current
GET /api/keyword Keyword-only compatibility route Deprecated before v1
GET /api/semantic Semantic-only compatibility route Deprecated before v1

Health

GET /api/health

The endpoint returns HTTP 200 with plain text:

OK

List databases

GET /api/list

Example response:

{
  "loaded": ["notes"],
  "registered": [
    {
      "db": "notes",
      "createAt": "2026-07-14T07:00:00Z"
    },
    {
      "db": "new_docs",
      "createAt": "2026-07-14T07:30:00Z"
    }
  ]
}
Field Meaning
loaded Names opened successfully during the current daemon startup
registered Durable entries currently present in db.json

A newly registered database can appear only in registered until restart.

GET /api/search?db=notes&q=what+is+RAG&limit=5

Query parameters

Parameter Required Default Behavior
db Yes — Selects a currently loaded database
q Yes — Exact query text used by the selected strategies
limit No 10 Result-row limit; valid values are 1–100
target No Both Use keyword or semantic to select one branch

An absent, non-numeric, non-positive, or greater-than-100 limit falls back to 10.

Combined response

With no target, KuraDB runs both branches concurrently:

{
  "keyword": [
    {
      "source": "/Users/example/Kura_notes/rag.md",
      "matches": [
        {
          "chunk": 1,
          "content": "RAG combines retrieval with generation."
        }
      ]
    }
  ],
  "semantic": [
    {
      "source": "/Users/example/Kura_notes/rag.md",
      "matches": [
        {
          "chunk": 1,
          "content": "RAG combines retrieval with generation."
        }
      ]
    }
  ]
}

A selected-out branch is omitted rather than returned as null. A selected branch with no matches is returned as an empty array.

Results are grouped by source. Every match exposes only chunk and content; internal row IDs, semantic scores, keyword hit counts, and totals are not part of the API contract.

Keyword target

GET /api/search?db=notes&q=vector+cache&target=keyword

The query is tokenized with gse, normalized to lowercase, deduplicated, and matched against active SQLite rows. Ranking uses matched-token count followed by row ID.

Semantic target

GET /api/search?db=notes&q=vector+cache&target=semantic

KuraDB obtains a 512-dimensional query embedding from cache or OpenAI, searches the in-memory vector bucket, removes hits below cosine score 0.3, then hydrates active rows from SQLite.

Compatibility routes

These routes invoke the same search handler with a fixed target:

GET /api/keyword?db=notes&q=vector+cache&limit=5
GET /api/semantic?db=notes&q=vector+cache&limit=5

They remain available to avoid breaking Agenvoy, but are marked for removal in v1. New consumers should use /api/search.

Error responses

Condition HTTP status Example body
Missing db 400 {"error":"db is required"}
Unknown or unloaded db 400 {"error":"\"name\" not exist"}
Missing q 400 {"error":"q is required"}
Search or registry failure 500 {"error":"..."}

If either concurrent search branch fails, the request returns an error rather than a partial result.

Read-only boundary

The router exposes no POST, PUT, PATCH, or DELETE routes. To add content, place files in a registered inbox and let the watcher-controlled indexing pipeline write to SQLite.

中文