Correct, Supersede, or Retract a Claim

The ledger never edits a line. Every change is a new line for the same claim key (predicate|from|to|qualifier) that supersedes the key's current head. The earlier lines stay in the history, so you can always see what was believed before.

Find the current head

In the app, the ledger panel shows the live claim for each designation and tie. Through the API, fold the subject and read claimId from the claim:

curl https://api.y2.dev/api/v2/ledger/subjects/sbj_0123456789abcdef01234567 \
  --header "Authorization: Bearer $Y2_API_KEY"

Strengthen a claim with a second source

In the app, record the same identifier again with the second page and a higher state such as cross-linked. The new line supersedes the head and keeps citing the head's evidence, so both pages support it.

Through the API, send supersedes with the head's claimId and cite both observations:

curl https://api.y2.dev/api/v2/ledger/records \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --json '{"kind":"claim","claim":{"predicate":"designated-by","from":"sbj_…","to":"dsg_…","supersedes":"clm_…head","confidence":90,"verification":"cross-linked","evidenceRefs":["obv_…first","obv_…second"]}}'

Close an interval when a page changes

When a later retrieval no longer shows an identifier, supersede the claim with an end bound instead of retracting it. The identifier held for the interval you observed.

{
  "kind": "claim",
  "claim": {
    "predicate": "designated-by",
    "from": "sbj_…",
    "to": "dsg_…",
    "supersedes": "clm_…head",
    "confidence": 75,
    "verification": "self-asserted",
    "validFrom": "2026-03-01T09:55:00Z",
    "validTo": "2026-04-02T09:00:00Z",
    "evidenceRefs": ["obv_…first-retrieval", "obv_…later-retrieval"],
    "note": "Sighting interval between two retrievals; the page may have listed it earlier."
  }
}

The end is exclusive. Leave a bound empty when no source gives it: an empty bound means unknown, never a guessed date.

Retract a mistaken claim

A retraction clears confidence, verification, and the interval, and still cites the observation that explains why, usually an analyst note:

{
  "kind": "claim",
  "claim": {
    "op": "retract",
    "predicate": "designated-by",
    "from": "sbj_…",
    "to": "dsg_…",
    "supersedes": "clm_…head",
    "evidenceRefs": ["obv_…note"],
    "note": "Attached on a shared name token only."
  }
}

The retracted head leaves the present picture and stays in history. You can assert the same key again later by superseding the retraction.

If the request is rejected

See Ledger record format for every rule code.