API reference

• personarequiredquery string (uuid)

  Required. Assertions are listed per persona, so a caller holding a person id resolves it first — GET /v1/persons/{id} returns that person's persona ids.

• kindquery optional string

  Keep only assertions whose kind equals this string exactly (e.g. "fact") — the same vocabulary a returned assertion's kind uses.

• statequery optional string

  Keep only assertions whose epistemic status equals this string exactly (e.g. "confirmed"). The parameter is spelled state; the field it filters is spelled status in the response body. Same vocabulary, different name.

• sourcequery optional string (uuid)

  Keep only assertions whose source equals this source id.

• sortquery optional string

  How to order the results. "created" — by the assertion's created_at_ms — is the only value accepted today; anything else is a 400. Absent ⇒ ordering by id.

• orderquery optional string

  asc (default, oldest first) or desc (newest first). A cursor is only valid against the order it was minted under.

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions/capture"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions/transcription-claim"

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions/unsourced"

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions/unsourced/tally"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions/{id}"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions/{id}/attach-evidence"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions/{id}/confirm"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions/{id}/mark-fabricated"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

404

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions/{id}/refute"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/assertions/{id}/supersede"

• personarequiredquery string (uuid)

  Required. Assertions are listed per persona, so a caller holding a person id resolves it first — GET /v1/persons/{id} returns that person's persona ids.

• kindquery optional string

  Keep only assertions whose kind equals this string exactly (e.g. "fact") — the same vocabulary a returned assertion's kind uses.

• statequery optional string

  Keep only assertions whose epistemic status equals this string exactly (e.g. "confirmed"). The parameter is spelled state; the field it filters is spelled status in the response body. Same vocabulary, different name.

• sourcequery optional string (uuid)

  Keep only assertions whose source equals this source id.

• sortquery optional string

  How to order the results. "created" — by the assertion's created_at_ms — is the only value accepted today; anything else is a 400. Absent ⇒ ordering by id.

• orderquery optional string

  asc (default, oldest first) or desc (newest first). A cursor is only valid against the order it was minted under.

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions/capture"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions/transcription-claim"

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions/unsourced"

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions/unsourced/tally"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions/{id}"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions/{id}/attach-evidence"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions/{id}/confirm"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions/{id}/mark-fabricated"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

404

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions/{id}/refute"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/assertions/{id}/supersede"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

201

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/associations"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

201

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/associations"

• includequery optional string

• limitquery optional integer (int32)

• cursorquery optional string

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/audit"

• includequery optional string

• limitquery optional integer (int32)

• cursorquery optional string

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/audit"

200

403

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/backup/config"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

PutBackupConfigRequest

• backup_root_path optional string

• cadence_hoursrequired integer (int32)

• enabledrequired boolean

• retentionrequired BackupRetentionDto

200

403

curl -sS -X PUT \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/backup/config"

• backup_rootrequiredquery string

200

403

422

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/backup/manifests"

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/backup/status"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

RestoreRequest

• backup_idrequired string

• backup_rootrequired string

• tree_idrequired string

200

403

404

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/restore"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

413

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/blobs"

• addressrequiredpath string

  sha256:<hex> content address

200 — application/octet-stream blob bytes

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/blobs/{address}"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

413

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/blobs"

• addressrequiredpath string

  sha256:<hex> content address

200 — application/octet-stream blob bytes

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/blobs/{address}"

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/capabilities"

• categoryquery optional string

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/citation-templates"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/citations"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/citations/render"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

202

400

404

curl -sS -X PUT \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/citations/{id}/elements"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

202

400

404

curl -sS -X PUT \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/citations/{id}/source-type"

• categoryquery optional string

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/citation-templates"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/citations"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/citations/render"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

202

400

404

curl -sS -X PUT \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/citations/{id}/elements"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

202

400

404

curl -sS -X PUT \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/citations/{id}/source-type"

• personaquery optional string (uuid)

  Only conflicts recorded against this persona.

• personquery optional string (uuid)

  Only conflicts about this person's identity, plus every conflict on a persona this person concludes over.

• limitquery optional integer (int32)

• cursorquery optional string

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/conflicts"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/conflicts/{id}/resolution"

• personaquery optional string (uuid)

  Only conflicts recorded against this persona.

• personquery optional string (uuid)

  Only conflicts about this person's identity, plus every conflict on a persona this person concludes over.

• limitquery optional integer (int32)

• cursorquery optional string

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/conflicts"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/conflicts/{id}/resolution"

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/diagnostics"

200 — text/plain redacted diagnostics bundle

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/diagnostics/bundle"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

SubmitFeedbackRequest

• email optional string

• messagerequired string

• name optional string

202 — delivered to the feedback service

403

422

429

502

503

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/feedback"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

201

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/events"

200 — text/event-stream of change notices

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/events/stream"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/events/{id}"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

202

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/events/{id}/corrections"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

201

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/events/{id}/participants"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

201

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/events"

200 — text/event-stream of change notices

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/events/stream"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/events/{id}"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

202

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/events/{id}/corrections"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

201

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/events/{id}/participants"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/gedcom/export"

• report_idquery optional string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/gedcom/loss-reports"

• version_hintquery optional string

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/gedcom/validate"

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/imports"

• filenamequery optional string

• allow_duplicatequery boolean

  Default false. Uploading bytes identical to a previous import refuses synchronously with 409 duplicate-import, before any job is spawned. Set this to import the same file a second time on purpose.

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

202

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/imports/gedcom"

• import_keyrequiredpath string

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

202

403

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/imports/{import_key}/undo"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/gedcom/export"

• report_idquery optional string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/gedcom/loss-reports"

• version_hintquery optional string

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/gedcom/validate"

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/imports"

• filenamequery optional string

• allow_duplicatequery boolean

  Default false. Uploading bytes identical to a previous import refuses synchronously with 409 duplicate-import, before any job is spawned. Set this to import the same file a second time on purpose.

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

202

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/imports/gedcom"

• import_keyrequiredpath string

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

202

403

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/imports/{import_key}/undo"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

422

500

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/integrations/claude-desktop/connect"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

422

500

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/integrations/claude-desktop/connect/preview"

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/integrations/harnesses"

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/jobs"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/jobs/{id}"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

202 — cancel requested

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/jobs/{id}/cancel"

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/jobs"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/jobs/{id}"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

202 — cancel requested

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/jobs/{id}/cancel"

• idsrequiredquery string

  Comma-separated entity ids.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/labels"

• idsrequiredquery string

  Comma-separated entity ids.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/labels"

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/media/unresolved"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/media/{id}/resolve"

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/media/unresolved"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/media/{id}/resolve"

• targetrequiredquery string

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/notes"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

201

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/notes"

• targetrequiredquery string

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/notes"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

201

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/notes"

• sourcequery optional string (uuid)

  Keep only pending items whose source equals this source id.

• proposerquery optional string

  Keep only pending items whose proposer equals this string — the model identifier the creating agent reported for itself.

• sortquery optional string

  How to order the results. "created" is the only value accepted today.

• orderquery optional string

  asc (default, oldest first) or desc (newest first). A cursor is only valid against the order it was minted under.

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

• group_byquery optional string

  Return the (already filtered and sorted) result set bucketed by source or by proposer instead of as a flat page. See this route's own description for how that changes the response shape.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/pending"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

403

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/pending/bulk-confirm"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/pending/{id}/defer"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/pending/{id}/undefer"

• sourcequery optional string (uuid)

  Keep only pending items whose source equals this source id.

• proposerquery optional string

  Keep only pending items whose proposer equals this string — the model identifier the creating agent reported for itself.

• sortquery optional string

  How to order the results. "created" is the only value accepted today.

• orderquery optional string

  asc (default, oldest first) or desc (newest first). A cursor is only valid against the order it was minted under.

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

• group_byquery optional string

  Return the (already filtered and sorted) result set bucketed by source or by proposer instead of as a flat page. See this route's own description for how that changes the response shape.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/pending"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

403

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/pending/bulk-confirm"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/pending/{id}/defer"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/pending/{id}/undefer"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/personas"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/personas/{id}"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

curl -sS -X PUT \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/personas/{id}/name-pieces"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/personas"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/personas/{id}"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

curl -sS -X PUT \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/personas/{id}/name-pieces"

• persona_idquery optional string (uuid)

• person_idquery optional string (uuid)

• window_startquery optional string

• window_endquery optional string

• edge_typesquery optional string

  Comma-separated shared_event / association / place_co_occurrence (default: all three).

• cursorquery optional string

• limitquery optional integer (int32)

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/fan/query"

• qquery optional string

  Free-text person-name search. Matches a name prefix first and falls back to a substring match when no prefix hits. Results come back in relevance order, so a sort/order given alongside q is accepted but ignored rather than rejected. Absent ⇒ no name filter.

• sortquery optional string

  How to order the results: * name — the person's display name. * surname — the display name's last whitespace-separated token, then the full name. * birth — earliest recorded birth year; people with no recorded birth sort last. * updated — when the person record was last touched. Any other value is a 400. Absent ⇒ a stable but arbitrary order by id. Sorting is applied before paging, so page 2 continues page 1.

• orderquery optional string

  asc (default, oldest first) or desc (newest first). A cursor is only valid against the order it was minted under.

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

202

400

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons"

• givenquery optional string

  Given name as typed so far (whitespace-separated pieces).

• surnamequery optional string

  Surname as typed so far.

• birthquery optional string

  Birth date in GEDCOM syntax (1832, ABT 1832, 12 JAN 1900, BEF 1900) — the same grammar every entry-form date field takes. Unparseable text 400s; scoring without a typed date would misrank and hide why.

• deathquery optional string

  Death date, same syntax and same strictness as birth.

• limitquery optional integer (int32)

  Max candidates returned (default 8, cap 50) — an entry form wants a short "did you mean?" list, not a page walk.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons/duplicate-candidates"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons/merge"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons/{id}"

• idrequiredpath string (uuid)

• expandquery optional string

  Comma-separated related record sets to inline: any of events, assertions, sources. Omit for the counts-only card. Each expanded list is capped at 100 rows. An unrecognised name is a 400, never a silently unexpanded card.

200

400

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons/{id}/card"

• idrequiredpath string (uuid)

• window_startquery optional string

• window_endquery optional string

• edge_typesquery optional string

  Comma-separated shared_event / association / place_co_occurrence (default: all three).

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons/{id}/fan-network"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

curl -sS -X PUT \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons/{id}/living-status"

• idrequiredpath string (uuid)

• generationsquery optional integer (int32)

  How many ancestor generations to resolve, from 1 to 10 (default 4). Anything outside that range is a 400.

200

400

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons/{id}/pedigree"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons/{id}/retract"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/persons/{id}/split"

• persona_idquery optional string (uuid)

• person_idquery optional string (uuid)

• window_startquery optional string

• window_endquery optional string

• edge_typesquery optional string

  Comma-separated shared_event / association / place_co_occurrence (default: all three).

• cursorquery optional string

• limitquery optional integer (int32)

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/fan/query"

• qquery optional string

  Free-text person-name search. Matches a name prefix first and falls back to a substring match when no prefix hits. Results come back in relevance order, so a sort/order given alongside q is accepted but ignored rather than rejected. Absent ⇒ no name filter.

• sortquery optional string

  How to order the results: * name — the person's display name. * surname — the display name's last whitespace-separated token, then the full name. * birth — earliest recorded birth year; people with no recorded birth sort last. * updated — when the person record was last touched. Any other value is a 400. Absent ⇒ a stable but arbitrary order by id. Sorting is applied before paging, so page 2 continues page 1.

• orderquery optional string

  asc (default, oldest first) or desc (newest first). A cursor is only valid against the order it was minted under.

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

202

400

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons"

• givenquery optional string

  Given name as typed so far (whitespace-separated pieces).

• surnamequery optional string

  Surname as typed so far.

• birthquery optional string

  Birth date in GEDCOM syntax (1832, ABT 1832, 12 JAN 1900, BEF 1900) — the same grammar every entry-form date field takes. Unparseable text 400s; scoring without a typed date would misrank and hide why.

• deathquery optional string

  Death date, same syntax and same strictness as birth.

• limitquery optional integer (int32)

  Max candidates returned (default 8, cap 50) — an entry form wants a short "did you mean?" list, not a page walk.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons/duplicate-candidates"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons/merge"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons/{id}"

• idrequiredpath string (uuid)

• expandquery optional string

  Comma-separated related record sets to inline: any of events, assertions, sources. Omit for the counts-only card. Each expanded list is capped at 100 rows. An unrecognised name is a 400, never a silently unexpanded card.

200

400

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons/{id}/card"

• idrequiredpath string (uuid)

• window_startquery optional string

• window_endquery optional string

• edge_typesquery optional string

  Comma-separated shared_event / association / place_co_occurrence (default: all three).

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons/{id}/fan-network"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

curl -sS -X PUT \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons/{id}/living-status"

• idrequiredpath string (uuid)

• generationsquery optional integer (int32)

  How many ancestor generations to resolve, from 1 to 10 (default 4). Anything outside that range is a 400.

200

400

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons/{id}/pedigree"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons/{id}/retract"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/persons/{id}/split"

• questionquery optional string (uuid)

• cursorquery optional string

• limitquery optional integer (int32)

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/proof-arguments"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

202

400

404

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/proof-arguments"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/proof-arguments/{id}"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/proof-arguments/{id}/export"

• questionquery optional string (uuid)

• cursorquery optional string

• limitquery optional integer (int32)

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/proof-arguments"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

202

400

404

422

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/proof-arguments"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/proof-arguments/{id}"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/proof-arguments/{id}/export"

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/proposals"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/proposals"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/proposals/{id}/approve"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/proposals/{id}/deny"

• limitquery optional integer (int32)

  How many rows to return. Clamped to 1..=500; defaults to 100 when absent. A value outside the range is clamped, not rejected.

• cursorquery optional string

  The next_cursor from the previous page. Omit it for the first page. Treat it as opaque, and keep every other query parameter identical while walking — a cursor is only valid against the query that minted it.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/proposals"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/proposals"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/proposals/{id}/approve"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/proposals/{id}/deny"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/redactions"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

403

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/redactions"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

201

400

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/relationships"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/relationships/reparent"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/relationships/unlink"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

201

400

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/relationships"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

409

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/relationships/reparent"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

400

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/trees/{tree_id}/relationships/unlink"

• sincequery optional string

  The cursor value from a previous brief; restricts every section to what changed after it. Omit for the full digest.

200

400

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/project/state"

• questionrequiredquery string (uuid)

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/research/log"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/research/log"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/research/log/capture"

• questionquery optional string (uuid)

• sessionquery optional string (uuid)

• personaquery optional string (uuid)

• sourcequery optional string (uuid)

• cursorquery optional string

• limitquery optional integer (int32)

• orderquery optional string

  "asc" (the default — oldest first) or "desc" (newest first). Anything else is a 400 rather than a silent fallback to the default. A cursor is only valid against the order it was minted under, so do not change order mid-walk.

200

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/research/log/entries"

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/research/log/negative-evidence"

• idrequiredpath string (uuid)

200

404

curl -sS -X GET \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/research/log/{id}"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404

curl -sS -X POST \
  -H "Authorization: Bearer $HEARTWOOD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  "http://127.0.0.1:$HEARTWOOD_PORT/v1/research/log/{id}/details"

• idrequiredpath string (uuid)

• idempotency-keyheader string (idempotency-key)

  Reserved for future request deduplication. Not deduplicated today — the key is accepted and shape-validated (200 characters maximum, printable non-whitespace ASCII, or the request is rejected), but a retried request carrying the same key applies a second time. Do not rely on it for at-most-once delivery yet. It exists now so that real deduplication can be turned on later without changing this API.

200

404