HTTP API
最後更新
daemon 在
127.0.0.1 提供的唯讀 JSON 端點，包含參數、回應與錯誤碼。基礎 URL
daemon 只監聽
127.0.0.1，並把位址寫入 ~/.config/kuradb/endpoint（例如 http://localhost:21182）。除非用 kura port set <port> 固定，連接埠為隨機；見設定。- BASE="$(cat ~/.config/kuradb/endpoint)"
| Method | 路徑 | 用途 |
|---|---|---|
GET | /api/health | 存活檢查，回傳純文字 OK |
GET | /api/list | 已載入與已註冊的資料庫 |
GET | /api/search | 在單一資料庫做關鍵字搜尋 |
GET | /api/keyword | /api/search 的舊版別名，target 固定為 keyword |
| 任意 | /mcp | 以 streamable HTTP 提供 MCP，僅在啟用遠端 MCP 時掛載（MCP 伺服器） |
GET /api/list
- curl "$BASE/api/list"
- {
- "loaded": ["notes"],
- "registered": [{ "db": "notes", "createAt": "2026-10-21T07:13:55Z" }]
- }
| 欄位 | 意義 |
|---|---|
loaded | 此 daemon 啟動時開啟、因此可搜尋的資料庫 |
registered | db.json 的所有項目，包含啟動後才新增或因開啟失敗而被略過的資料庫 |
GET /api/search
- curl "$BASE/api/search?db=notes&q=sqlite%20wal&limit=5"
| 參數 | 必填 | 值 |
|---|---|---|
db | 是 | loaded 中的名稱 |
q | 是 | 以空白分隔的關鍵字 |
limit | 否 | 1 到 100 個 chunk；其他值改用 10 |
target | 否 | keyword 或省略 |
回應為
{"keyword": [...]}，chunk 依來源檔分組；比對與排序規則見關鍵字搜尋。/api/keyword 接受相同的 db、q、limit 參數，保留它是為了讓既有的 Agenvoy 版本不中斷，並標記於 v1 棄用。錯誤
錯誤回傳 JSON
{"error": "<message>"}。| 狀態碼 | 訊息 | 原因 |
|---|---|---|
| 400 | db is required | 缺少 db |
| 400 | "<name>" not exist | db 不是已載入的資料庫 |
| 400 | invalid argument: q is required | q 缺少或為空 |
| 400 | invalid argument: unknown target "<value>" | target 不是 keyword |
| 500 | 資料庫錯誤訊息 | 查詢失敗，或 /api/list 無法讀取 db.json |