Invocation#

bash

spis serve --port PORT

Binds the loopback address on PORT (0 lets the system choose; Spis Desktop passes 0), prints exactly one line, {"ready":true,"port":N}, and from then on writes nothing to stdout. Every endpoint runs the spis subcommand the CLI would run, as a child of the same executable, one job at a time; there is no second implementation behind the HTTP surface.

Endpoints#

GET /v1/health answers {"status":"ok"}.
GET /v1/docs-status, POST /v1/docs-search (query, optional site and a positive limit) and POST /v1/docs-show (site, url) answer with the JSON document spis docs-corpus status|search|show prints, unchanged.
POST /v1/corpus-adopt (absolute path), /v1/catalogs-check, /v1/drift, /v1/verify, /v1/capture-dry-run (catalog), /v1/reference-add (slug, name, sourceUrl, category, selectionNote, visual), /v1/reference-remove (slug, positive number, optional force), /v1/catalog-add (slug, title, optional description; runs spis catalog-type add), /v1/catalog-edit (slug and at least one of title, description, status, rename; runs catalog-type edit) and /v1/catalog-remove (slug, optional force; runs catalog-type remove) stream NDJSON: zero or more {"type":"log","stream":"stdout"|"stderr","chunk":…} lines as the command writes them, then exactly one {"type":"result","status":N,"json":{…}} with the command's exit status and, on failure, {"error": <its refusal sentence>}.

Refusals#

Without --port PORT, or with anything else: usage: spis serve --port PORT (0 lets the system choose one), exit 2.
A port that cannot be bound: cannot listen on the loopback address, port PORT: …, exit 1.
Before a stream starts, a refusal is a non-2xx {"error": sentence}: 404 unknown endpoint: METHOD PATH; 400 request body is not valid JSON, request body must be a JSON object, or the missing field named (for example adding a record requires a source URL); 500 for a document command's own refusal (its last stderr line without error: ) or spis could not start: ….