# HTTP API

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](/configuration).

```bash
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](/mcp-server)) |

## GET /api/list

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

```json
{
  "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

```bash
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](/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` |

## Related Pages

- [Keyword Search](/keyword-search)
- [MCP Server](/mcp-server)