文件
首頁 GitHub

API 參考

透過本機唯讀 Gin HTTP API 查詢 KuraDB。

Base URL

KuraDB 綁定至 127.0.0.1，並將選定的 URL 寫入 ~/.config/kuradb/endpoint。

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

目前所有 route 都使用 GET，並位於 /api group 下。服務不提供內容 mutation endpoint。

Endpoint 摘要

Method Path 用途 狀態
GET /api/health 檢查 process 可用性 現行
GET /api/list 檢視已註冊與已載入資料庫 現行
GET /api/search 執行 keyword、semantic 或兩者搜尋 現行
GET /api/keyword Keyword-only compatibility route v1 前 deprecated
GET /api/semantic Semantic-only compatibility route v1 前 deprecated

Health

GET /api/health

Endpoint 回傳 HTTP 200 與純文字：

OK

列出資料庫

GET /api/list

Response 範例：

{
  "loaded": ["notes"],
  "registered": [
    {
      "db": "notes",
      "createAt": "2026-07-14T07:00:00Z"
    },
    {
      "db": "new_docs",
      "createAt": "2026-07-14T07:30:00Z"
    }
  ]
}
Field 意義
loaded 目前 daemon 啟動時成功開啟的名稱
registered db.json 中目前存在的持久 entry

新註冊資料庫重新啟動前可能只出現在 registered。

GET /api/search?db=notes&q=什麼是RAG&limit=5

Query parameter

Parameter 必要 預設 行為
db 是 — 選擇目前已載入的資料庫
q 是 — 所選 strategy 使用的完整 query text
limit 否 10 Result-row limit；有效值為 1–100
target 否 兩者 使用 keyword 或 semantic 選擇單一 branch

limit 缺少、非數字、非正數或大於 100 時，會 fallback 為 10。

Combined response

未指定 target 時，KuraDB 會並行執行兩個 branch：

{
  "keyword": [
    {
      "source": "/Users/example/Kura_notes/rag.md",
      "matches": [
        {
          "chunk": 1,
          "content": "RAG 結合檢索與生成。"
        }
      ]
    }
  ],
  "semantic": [
    {
      "source": "/Users/example/Kura_notes/rag.md",
      "matches": [
        {
          "chunk": 1,
          "content": "RAG 結合檢索與生成。"
        }
      ]
    }
  ]
}

未選擇的 branch 會直接省略，而不是回傳 null。已選 branch 若無 match，則回傳空 array。

Result 會依 source 分組。每個 match 只暴露 chunk 與 content；內部 row ID、semantic score、keyword hit count 與 total 不屬於 API contract。

Keyword target

GET /api/search?db=notes&q=向量快取&target=keyword

Query 會經過 gse tokenization、lowercase normalization 與 deduplication，再比對 SQLite active row。Ranking 依 matched-token count，再依 row ID。

Semantic target

GET /api/search?db=notes&q=向量快取&target=semantic

KuraDB 從 cache 或 OpenAI 取得 512 維 query embedding，搜尋記憶體 vector bucket，移除 cosine score 低於 0.3 的 hit，再從 SQLite hydrate active row。

Compatibility route

下列 route 使用固定 target 呼叫相同 search handler：

GET /api/keyword?db=notes&q=向量快取&limit=5
GET /api/semantic?db=notes&q=向量快取&limit=5

為避免破壞 Agenvoy，它們目前仍可使用，但已標示將於 v1 移除。新 consumer 應使用 /api/search。

Error response

條件 HTTP status Body 範例
缺少 db 400 {"error":"db is required"}
未知或未載入的 db 400 {"error":"\"name\" not exist"}
缺少 q 400 {"error":"q is required"}
Search 或 registry failure 500 {"error":"..."}

若並行 search branch 任一失敗，request 會回傳 error，而不是 partial result。

唯讀邊界

Router 不暴露 POST、PUT、PATCH 或 DELETE route。若要新增內容，請將檔案放入已註冊 inbox，讓 watcher-controlled indexing pipeline 寫入 SQLite。

EN