# HTTP API

daemon 在 `127.0.0.1` 提供的唯讀 JSON 端點，包含參數、回應與錯誤碼。

## 基礎 URL

daemon 只監聽 `127.0.0.1`，並把位址寫入 `~/.config/kuradb/endpoint`（例如 `http://localhost:21182`）。除非用 `kura port set <port>` 固定，連接埠為隨機；見[設定](/zh/configuration)。

```bash
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 伺服器](/zh/mcp-server)） |

## GET /api/list

```bash
curl "$BASE/api/list"
```

```json
{
  "loaded": ["notes"],
  "registered": [{ "db": "notes", "createAt": "2026-10-21T07:13:55Z" }]
}
```

| 欄位 | 意義 |
|---|---|
| `loaded` | 此 daemon 啟動時開啟、因此可搜尋的資料庫 |
| `registered` | `db.json` 的所有項目，包含啟動後才新增或因開啟失敗而被略過的資料庫 |

## GET /api/search

```bash
curl "$BASE/api/search?db=notes&q=sqlite%20wal&limit=5"
```

| 參數 | 必填 | 值 |
|---|---|---|
| `db` | 是 | `loaded` 中的名稱 |
| `q` | 是 | 以空白分隔的關鍵字 |
| `limit` | 否 | 1 到 100 個 chunk；其他值改用 10 |
| `target` | 否 | `keyword` 或省略 |

回應為 `{"keyword": [...]}`，chunk 依來源檔分組；比對與排序規則見[關鍵字搜尋](/zh/keyword-search)。`/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` |

## 相關頁面

- [關鍵字搜尋](/zh/keyword-search)
- [MCP 伺服器](/zh/mcp-server)