Build a tool against the local API

Heartwood is closed source, but the daemon exposes a documented local API — the same surface the app's own AI features use. Ten minutes to your first capture.

1. Find the daemon

The daemon binds 127.0.0.1:0 (an OS-assigned port — no fixed ports, ever) and writes a discovery file inside its data directory containing the port and a bearer token:

{
  "port": 51234,
  "token": "…"
}

Read that file, then address every request at http://127.0.0.1:<port>/v1/… with header Authorization: Bearer <token>. There is no remote endpoint and never will be — everything is loopback-only.

2. Open a research question

Most write operations expect a research context. Start one:

curl -s http://127.0.0.1:$PORT/v1/research/questions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "Who were John Smith'"'"'s parents?"}'

3. Capture an assertion

Capture is how a claim enters the system — always attached to evidence, never a bare fact:

curl -s http://127.0.0.1:$PORT/v1/assertions/capture \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "...": "see the API reference for the full CaptureRequest shape" }'

AI-originated captures land in the pending lane — visibly distinct, and structurally unable to feed a proof argument, export, or graft until a human confirms it against the source (see the methodology guide).

4. Confirm it

curl -s -X POST http://127.0.0.1:$PORT/v1/assertions/$ID/confirm \
  -H "Authorization: Bearer $TOKEN"

Confirmation is a human-only checkpoint — it requires a human token/context, the same pattern as marking something fabricated.

Full reference

Every route, request/response shape, and the application/problem+json error model: see the API reference.