HTTP API
Last updated
The read-only JSON endpoints the daemon serves on
127.0.0.1, with their parameters, responses, and error codes.Base URL
The daemon listens on
127.0.0.1 only and writes its address to ~/.config/kuradb/endpoint (for example http://localhost:21182). The port is random unless pinned with kura port set <port>; see Configuration.- BASE="$(cat ~/.config/kuradb/endpoint)"
| Method | Path | Purpose |
|---|---|---|
GET | /api/health | Liveness check, returns the plain text OK |
GET | /api/list | Loaded and registered databases |
GET | /api/search | Keyword search in one database |
GET | /api/keyword | Legacy alias of /api/search with the target fixed to keyword |
| any | /mcp | MCP over streamable HTTP, mounted only when remote MCP is enabled (MCP Server) |
GET /api/list
- curl "$BASE/api/list"
- {
- "loaded": ["notes"],
- "registered": [{ "db": "notes", "createAt": "2026-10-21T07:13:55Z" }]
- }
| Field | Meaning |
|---|---|
loaded | Databases opened by this daemon at startup and therefore searchable |
registered | Every entry in db.json, including databases added after startup or skipped because they failed to open |
GET /api/search
- curl "$BASE/api/search?db=notes&q=sqlite%20wal&limit=5"
| Parameter | Required | Value |
|---|---|---|
db | Yes | A name from loaded |
q | Yes | Space-separated keywords |
limit | No | 1 to 100 chunks; anything else falls back to 10 |
target | No | keyword or omitted |
The response is
{"keyword": [...]} with chunks grouped by source file; matching and ranking rules are on Keyword Search. /api/keyword takes the same db, q, and limit parameters; it is kept so existing Agenvoy builds keep working and is marked for deprecation in v1.Errors
Errors return a JSON body
{"error": "<message>"}.| Status | Message | Cause |
|---|---|---|
| 400 | db is required | db missing |
| 400 | "<name>" not exist | db is not a loaded database |
| 400 | invalid argument: q is required | q missing or empty |
| 400 | invalid argument: unknown target "<value>" | target is not keyword |
| 500 | Database error text | Query failure, or db.json cannot be read on /api/list |