Configuration¶
The API is JSON on loopback port 1416. There is no browser UI.
Where things live¶
| Item | What it is |
|---|---|
127.0.0.1:1416 |
Authenticated REST API. |
/etc/haystack/client.json |
base_url and api_token for the ubuntu client. root:ubuntu, mode 0640. |
/etc/haystack/config.json |
Service configuration, including an optional provider. root:haystack, mode 0640. |
/var/lib/haystack/documents.sqlite3 |
Documents. The service uses SQLite WAL. |
~/haystack-results/ |
Demo evidence. |
sushi-haystack |
status, demo, and read. |
api_token must be the same value in both configuration files. Treat both
files as secrets.
Calls¶
POST /documents/run accepts operation upsert, read, or query.
Uploads replace a document with the same id. Ids use letters, numbers,
underscores, dots, or hyphens, and are at most 128 characters. A query
accepts question and optional generate: true. Sources include ids, the
exact content, and BM25 scores. GET /status and GET /openapi.json also
require the Bearer token.
The public guide's client reads client.json and does not print the token.
Run it as ubuntu. Keep the token out of the command line. The same calls
are upsert with documents, query with question, and read with
ids.
Optional model¶
No weights or provider allowance are included. Set the provider object's
base_url to an API base that ends in /v1, model to the exact model
id, and api_key to the credential. Preserve api_token and state_dir.
Leave ownership root:haystack and mode 0640. Use sudoedit in an
unrecorded session.
The endpoint must support temperature, max_tokens, and
/chat/completions. A local provider must bind to a port other than 1416.
A remote provider must use HTTPS.
Queries with generate: true send retrieved document text and the question
to that provider. Read the sources. An answer can be wrong and still contain
a citation.
Last updated November 11, 2026 · Suggest an improvement