Correct, Supersede, or Retract a Claim

Each correction replaces the current head of a claim key: predicate|from|to|qualifier. Earlier records remain in the ledger.

API requests require a workspace-bound key with ledger:read and ledger:write. Set Y2_SUBJECT_ID to the subject's actual ID. Replace the IDs in the JSON templates below with IDs from your ledger.

Find the current headCopy Anchor Link

The app shows the live claim for each designation and relationship. For API access, read the subject:

curl --fail --silent --show-error \
  "https://api.y2.dev/api/v2/ledger/subjects/$Y2_SUBJECT_ID" \
  --header "Authorization: Bearer $Y2_API_KEY"

Retain the current claimId for the claim you will replace.

Strengthen a claim with a second sourceCopy Anchor Link

In the app, record the same identifier with the second source. Select cross-linked only when the evidence supports it. Y2 retains the earlier evidence and supersedes the previous claim.

Through the API, append the second observation first. Then submit a claim with both evidence IDs and the current head:

{
  "kind": "claim",
  "claim": {
    "predicate": "designated-by",
    "from": "SUBJECT_ID",
    "to": "DESIGNATOR_ID",
    "supersedes": "CURRENT_CLAIM_ID",
    "confidence": 90,
    "verification": "cross-linked",
    "evidenceRefs": ["FIRST_OBSERVATION_ID", "SECOND_OBSERVATION_ID"]
  }
}

Choose a confidence value supported by your evidence. The value shown here illustrates the field. Submit the payload with Append a record.

Close an interval when a page changesCopy Anchor Link

If a later retrieval no longer shows the identifier, supersede the claim with validTo. Cite both retrievals. Retain the claim's confidence and verification state.

Use source-supported dates. If only retrievals establish the dates, describe the interval as a sighting interval in note. The end is exclusive. Omit an unknown bound instead of guessing it.

Retract a mistaken claimCopy Anchor Link

First record an observation that explains the error, usually an analyst note. Then append a retraction:

{
  "kind": "claim",
  "claim": {
    "op": "retract",
    "predicate": "designated-by",
    "from": "SUBJECT_ID",
    "to": "DESIGNATOR_ID",
    "supersedes": "CURRENT_CLAIM_ID",
    "evidenceRefs": ["EXPLANATION_OBSERVATION_ID"],
    "note": "The earlier attachment relied only on a shared name."
  }
}

Omit confidence, verification, and interval fields on a retraction. The retracted claim leaves the current view but remains in history. A later assertion must supersede the retraction.

If the request is rejectedCopy Anchor Link

See record rules for other errors.