Verification API

TrackForge verification APIs expose certificate and proof data so a third party can check the methodology hash, evidence hashes, Merkle root, and OpenTimestamps proof state.

Compatibility Surface

Some deployed endpoints and fields still use historical names such as golden_record_count or tier-count fields. Those names are legacy compatibility fields. Current certificate-facing methodology uses AAA-D rating events and leakage-taxonomy state.

Current Rating Event Shape

New rating-event payloads should expose:

{
  "rating_event_id": "...",
  "subject_type": "catalogue",
  "subject_id": "...",
  "rating": "BB",
  "rating_scale": "TRACKFORGE_AAA_D",
  "methodology_version": "v1.1",
  "methodology_hash": "...",
  "taxonomy_version": "v...",
  "workflow_version": "v...",
  "jurisdictional_scope": ["UK", "US"],
  "snapshot_run_id": "...",
  "snapshot_at": "...",
  "leakage_vector_hash": "...",
  "evidence_packet_hash": "...",
  "merkle_root": "...",
  "ots_status": "pending"
}

Current M58 proofs should also include PRS/WACD agreement-binding and ISWC coverage summaries where those inputs are in scope.

Verification Requirements

A verifier should be able to:

1. Recompute the methodology hash from the methodology artefact.
2. Recompute evidence packet hashes from canonical JSON.
3. Rebuild the Merkle root from the rating event's evidence packet set.
4. Confirm the rating event references the same run, methodology hash, workflow version, taxonomy version, and scope.
5. Verify .ots proof files when ots_status is confirmed.

Public Verification Endpoint

The historical public endpoint verifies submitted canonical JSON against stored certification records. Current verification pages should additionally show rating event fields when available.

POST /api/v1/certifications/verify

Request:

{
  "canonical_json": "<deterministic JSON string>"
}

Response:

{
  "verified": true,
  "record_hash": "64-character sha256 hex",
  "certification": {
    "batch_id": "...",
    "merkle_root": "...",
    "methodology_hash": "...",
    "rating_event_id": "..."
  },
  "anchors": [
    {
      "chain": "bitcoin",
      "status": "confirmed",
      "tx_id": "...",
      "block_number": 879234
    }
  ]
}

Forge Grade Proof Endpoint

Forge exposes the current M58 grade proof for a subject so internal operators and authorised verifiers can retrieve the rating event and proof wrapper directly.

GET /ops/api/forge/catalogs/{catalog_id}/grade/proof

The response should identify the current certification root for the subject and return the same proof concepts found in the M58 ZIP:

• rating_event_proof
• rating_event
• leakage_vector
• snapshot_links
• manifest or file-hash equivalent

The current root is the active Merkle/root commitment for the latest certification event in the subject's version chain. Historical roots remain valid for their own events, but current reliance should use the root marked current by the certification chain.

Legacy Batch Fields

The following fields may remain in compatibility endpoints:

Field	Current interpretation
golden_record_count	Legacy count retained for historical APIs. Not the current rating basis.
tier_gold_count	Legacy completeness-tier count.
tier_silver_count	Legacy completeness-tier count.
tier_bronze_count	Legacy completeness-tier count.
tier_declared_count	Legacy completeness-tier count.
catalog_grade	Historical or transitional field; current outputs should prefer rating.

Any UI that displays these fields beside a current rating should label them as legacy diagnostics.

Proof Bundle Endpoint

GET /api/v1/certifications/{catalog_id}/proof-bundle

The legacy public bundle endpoint may still return historical certification archives. The current Forge M58 proof ZIP is available to authorised operators at:

GET /ops/api/forge/catalogs/{catalog_id}/grade/proof-bundle

The current M58 bundle should include:

• README.md.
• manifest.json.
• proof/rating_event_proof.json.
• proof/rating_event.json.
• proof/leakage_vector.json.
• proof/snapshot_links.json.
• methodology/methodology.json.
• Legacy or enhanced chain-of-title records only where needed for backwards compatibility or richer certification bundles.

Status Semantics

Status	Meaning
pending	Submitted or awaiting confirmation; not confirmed.
confirmed	Confirmed proof state.
failed	Anchoring or verification failed.
not_submitted	No external proof submission exists.
local_only	Local witness only; not public blockchain confirmation.