# API reference — per-resource markdown

Machine-readable companion to the interactive reference ([api/index.html](index.html)) — every route, grouped by resource, sourced from the committed OpenAPI artifact (`crates/daemon/openapi/v1.json`). One file per resource.

## Calling the API

The API is loopback-only: the daemon binds `127.0.0.1` on an OS-assigned port (never a fixed one) and writes a discovery file, `discovery.json`, into its data directory, carrying that port and a bearer token. On macOS — the only platform Heartwood ships today — that data directory is `~/Library/Application Support/com.twiglylabs.heartwood`, so the full path is `~/Library/Application Support/com.twiglylabs.heartwood/discovery.json`. (A Windows build is planned but not available yet; there is no Windows data-dir path to give until one ships.) Read the port and token from that file, then send the token as a bearer credential on every request:

```
Authorization: Bearer <token from the discovery file>
```

The examples below use `$HEARTWOOD_PORT` and `$HEARTWOOD_TOKEN` for those two values. Use the token from `discovery.json` itself, not a "human-token" file that may sit next to it — that second file is a separately minted credential for the app's own UI only and will not authenticate a request here.

## Build a tool

Heartwood is closed source, but not a black box: this documented local surface — the same one the app's own AI features use — is yours to build on. Point your coding agent at [llms.txt](https://heartwood.family/llms.txt) and the per-resource docs below, describe the tool you want, and let it write the client — no hand-maintained SDK needed. Building "give my AI a new capability" instead of a standalone script? See [Connect your AI](../getting-started-ai.md) instead.

- [assertions](resources/assertions.md): Evidence-backed claims: capture, confirm, refute, attach evidence. (22 routes)
- [associations](resources/associations.md): Associations between persons. (2 routes)
- [audit](resources/audit.md): The audit trail. (2 routes)
- [backup](resources/backup.md): Tree backup: on-demand snapshot, configuration, and status. (5 routes)
- [blobs](resources/blobs.md): Content-addressed binary evidence storage. (4 routes)
- [capabilities](resources/capabilities.md): The daemon's advertised capabilities. (1 route)
- [citations](resources/citations.md): Citation templates, rendering, and structured elements. (10 routes)
- [conflicts](resources/conflicts.md): Detected conflicts between assertions. (4 routes)
- [diagnostics](resources/diagnostics.md): Diagnostics summary and downloadable bundle. (3 routes)
- [events](resources/events.md): Life events: creation, participants, corrections, and the live change-event stream. (10 routes)
- [gedcom](resources/gedcom.md): GEDCOM (family file) import, export, validation, and loss reports. (12 routes)
- [integrations](resources/integrations.md): Third-party integration setup (Claude Desktop). (3 routes)
- [jobs](resources/jobs.md): Background jobs (currently GEDCOM import). (6 routes)
- [labels](resources/labels.md): labels (2 routes)
- [media](resources/media.md): media (4 routes)
- [notes](resources/notes.md): Free-text notes. (4 routes)
- [pending](resources/pending.md): The pending lane: assertions awaiting confirmation, deferral, or bulk action. (8 routes)
- [personas](resources/personas.md): A person's per-source name/identity claims. (6 routes)
- [persons](resources/persons.md): People in the tree, including the fan-network relationship view. (24 routes)
- [proof-arguments](resources/proof-arguments.md): Proof arguments: assembling and exporting a case for a conclusion. (8 routes)
- [proposals](resources/proposals.md): Merge proposals: propose, approve, deny. (8 routes)
- [redactions](resources/redactions.md): Redacting a record. (2 routes)
- [relationships](resources/relationships.md): relationships (6 routes)
- [research](resources/research.md): Research questions, sessions, plans, and the research log (GPS reasonably-exhaustive-search coverage). (56 routes)
- [sessions](resources/sessions.md): sessions (6 routes)
- [sources](resources/sources.md): Source records citations are built from. (12 routes)
- [telemetry](resources/telemetry.md): The local, never-leaves-the-machine telemetry queue. (5 routes)
- [trees](resources/trees.md): Tree management: create, rename, archive, and the active-tree selection. (14 routes)
- [undo](resources/undo.md): undo (4 routes)
- [updates](resources/updates.md): The auto-updater: status, check, restart. (6 routes)