Skip to content

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.

sudo systemctl restart haystack.service

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