REST API
The daemon's HTTP API on localhost:11500, plus the MCP endpoint.
The daemon serves JSON over HTTP on localhost:11500. It listens on localhost only and has no auth in v0; do not expose it beyond the machine.
POST /api/query
Search. This is the endpoint your scripts want.
curl -s -X POST localhost:11500/api/query \
-d '{"query": "termination clause", "tag": "", "limit": 5}'Request:
| Field | Type | Meaning |
|---|---|---|
query | string | Required. Search text |
tag | string | Optional. Restrict to folders with this tag |
limit | int | Optional. Max results, default 10, cap 100 |
Response:
{
"results": [
{
"path": "/Users/you/Documents/contracts/msa.pdf",
"page": 4,
"chunk": 11,
"snippet": "Either party may terminate...",
"score": 0.0322
}
]
}page is 1-based and present for paginated formats; 0 means the format has no pages and chunk is the citation.
GET /api/health
Liveness plus identity. Clients use db to confirm they are talking to the daemon for the right index.
{ "ok": true, "version": "0.1.0", "db": "/Users/you/.haypile/haypile.db", "model": "bundled/all-MiniLM-L6-v2" }GET /api/status
Everything hay status shows: uptime, sources, counts, pending indexing jobs, and the measured outbound connection count.
GET /api/sources
Indexed folders with counts.
POST /api/sources
Index and watch a folder or file. Runs synchronously and returns the indexing stats.
curl -s -X POST localhost:11500/api/sources \
-d '{"path": "/Users/you/Documents", "tag": "personal"}'DELETE /api/sources
Un-index and un-watch. Body: {"path": "..."}. Returns {"removed": true} or false if the path was not indexed.
POST /mcp
The MCP endpoint (Streamable HTTP transport, JSON-RPC 2.0). Supports initialize, tools/list, tools/call, and ping. Tools:
| Tool | Arguments | Returns |
|---|---|---|
search_documents | query (required), tag, limit | Cited passages as text |
list_sources | none | Indexed folders with counts |
Point any MCP client at http://localhost:11500/mcp, or use hay mcp-stdio for stdio-transport clients.
Errors
Non-200 responses carry {"error": "message"}. Bad requests are 400, server faults 500. MCP tool failures come back inside the JSON-RPC result with isError: true so agent models can read and react to them.