---
sidebar_position: 1
title: Verification API
description: "Current and legacy TrackForge verification endpoints: check the methodology hash, evidence hashes, Merkle root and OpenTimestamps proof state of any certificate."
keywords:
  - verification API
  - rating event
  - certificate verification
  - Merkle proof API
  - legacy certification API
---

# 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.

:::caution[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:

```json
{
  "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.

```http
POST /api/v1/certifications/verify
```

Request:

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

Response:

```json
{
  "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.

```http
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

```http
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:

```http
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. |