Verification API

TrackForge exposes nine certification endpoints under the /api/v1/certifications prefix. One endpoint is fully public; the remainder require authentication.

All authenticated endpoints use Clerk bearer tokens. The base URL for all endpoints is your TrackForge instance (e.g. https://api.trackforge.studio).

Endpoint summary

Method	Path	Auth	Description
POST	/verify	None (public)	Verify a golden record against certified data
GET	/batch/{batch_id}	User	Batch certification status with anchor info
GET	/{catalog_id}/certificate/{isrc}	User	Download per-track certificate (JSON)
GET	/{catalog_id}/report	User	Download full catalogue certification report (JSON)
GET	/{catalog_id}/chain-of-title	User	Download chain of title export (JSON)
GET	/{catalog_id}/proof-bundle	User	Download complete proof bundle (ZIP)
GET	/{catalog_id}/{isrc}	User	Track certification status
GET	/{catalog_id}	User	Catalogue certification summary
POST	/{catalog_id}/certify	Admin	Trigger certification workflow

---

Public verification endpoint

POST /api/v1/certifications/verify

Authentication: None. This endpoint is intentionally public so that any third party can independently verify a golden record without needing a TrackForge account.

Rate limit: 100 requests per minute per IP address. Exceeding this limit returns 429 Too Many Requests.

Request body

{
  "canonical_json": "<deterministic JSON string of the golden record>"
}

Field	Type	Required	Description
canonical_json	string	Yes	The canonical JSON representation of the golden record. Must be serialised using the exact rules defined in the Canonical JSON Schema.

Response body

{
  "verified": true,
  "record_hash": "a1b2c3d4e5f6...64 hex characters",
  "certification": {
    "isrc": "GBAYE0100538",
    "certified_at": "2026-01-15T14:30:00Z",
    "certification_version": "1.0",
    "is_current": true,
    "batch_id": "batch_01HZ...",
    "merkle_root": "e7f8a9b0c1d2...64 hex characters",
    "methodology_hash": "a122860e4aae34fd...64 hex characters"
  },
  "anchors": [
    {
      "chain": "bitcoin",
      "status": "confirmed",
      "tx_id": "3a1b2c3d4e5f...64 hex characters",
      "block_number": 879234,
      "block_timestamp": "2026-01-15T15:42:00Z"
    }
  ]
}

Field	Type	Description
verified	boolean	Whether the submitted canonical JSON matches a certified record.
record_hash	string	SHA-256 hex digest of the submitted canonical JSON. Always returned, even if verified is false.
certification	object | null	Certification metadata. null if no matching certification exists.
certification.isrc	string	The ISRC of the certified track.
certification.certified_at	string	ISO 8601 timestamp of certification.
certification.certification_version	string	Version of the certification schema (e.g. "1.0").
certification.is_current	boolean	Whether this is the current (latest) certification for the track.
certification.batch_id	string	Identifier of the certification batch.
certification.merkle_root	string	Merkle root of the batch's Merkle tree.
certification.methodology_hash	string	SHA-256 of the rating methodology in effect at certification time.
anchors	array	Blockchain anchor records. Empty if not yet anchored.
anchors[].chain	string	Blockchain name (currently always "bitcoin").
anchors[].status	string	Anchor status: "pending", "submitted", or "confirmed".
anchors[].tx_id	string	Blockchain transaction ID containing the timestamp.
anchors[].block_number	integer	Block number.
anchors[].block_timestamp	string	Block timestamp (ISO 8601).

Example: verified record

curl -X POST https://api.trackforge.studio/api/v1/certifications/verify \
  -H "Content-Type: application/json" \
  -d '{"canonical_json": "{\"artist\":\"Iron Maiden\",\"certification_version\":\"1.0\",\"duration_ms\":437000,\"isrc\":\"GBAYE0100538\",\"iswc\":\"T-010.466.720-3\",\"performers\":[{\"name\":\"Bruce Dickinson\",\"role\":\"vocals\"},{\"name\":\"Dave Murray\",\"role\":\"guitar\"}],\"release_date\":\"2000-05-29\",\"title\":\"The Wicker Man\",\"writers\":[{\"ipi\":\"00026781411\",\"name\":\"Adrian Smith\",\"role\":\"composer\",\"share\":33.33},{\"ipi\":\"00026781422\",\"name\":\"Bruce Dickinson\",\"role\":\"composer\",\"share\":33.33},{\"ipi\":\"00026781433\",\"name\":\"Steve Harris\",\"role\":\"composer\",\"share\":33.34}]}"}'

Example: unverified record

If the canonical JSON does not match any certified record, the response returns verified: false with a null certification:

{
  "verified": false,
  "record_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "certification": null,
  "anchors": []
}

Error responses

Status	Condition
422	Missing or malformed canonical_json field.
429	Rate limit exceeded (100 requests/minute/IP).
500	Internal server error.

---

Authenticated endpoints

All endpoints below require a valid Clerk bearer token in the Authorization header:

Authorization: Bearer <clerk_session_token>

GET /api/v1/certifications/batch/{batch_id}

Return the certification status for a batch, including blockchain anchor information.

Path parameters

Parameter	Type	Description
batch_id	string	The certification batch identifier.

Response body

{
  "batch_id": "batch_01HZ...",
  "catalog_id": "cat_01HZ...",
  "merkle_root": "e7f8a9b0c1d2...64 hex characters",
  "track_count": 142,
  "golden_record_count": 138,
  "status": "confirmed",
  "certified_at": "2026-01-15T14:30:00Z",
  "confirmed_at": "2026-01-15T15:42:00Z",
  "certification_version": "1.0",
  "methodology_hash": "a122860e4aae34fd...64 hex characters",
  "standard_version": "v1.0",
  "anchors": [
    {
      "chain": "bitcoin",
      "status": "confirmed",
      "tx_id": "3a1b2c3d...",
      "block_number": 879234,
      "block_timestamp": "2026-01-15T15:42:00Z"
    }
  ]
}

Field	Type	Description
batch_id	string	Batch identifier.
catalog_id	string	Catalogue the batch belongs to.
merkle_root	string	Merkle root hash (64 hex characters).
track_count	integer	Total tracks in the catalogue.
golden_record_count	integer	Tracks that qualified as Golden Records.
status	string	Batch status: "certified", "anchoring", "confirmed".
certified_at	string | null	When certification was issued.
confirmed_at	string | null	When the blockchain anchor was confirmed.
certification_version	string | null	Schema version.
methodology_hash	string | null	SHA-256 of the rating methodology ruleset in effect.
standard_version	string | null	Rating standard version (e.g. "v1.0").
anchors	array	Blockchain anchors (same schema as /verify).

---

GET /api/v1/certifications/{catalog_id}/certificate/{isrc}

Download a per-track certification document as a JSON file.

Path parameters

Parameter	Type	Description
catalog_id	string	Catalogue identifier.
isrc	string	ISRC of the track.

Response

Returns a JSON file download (Content-Disposition: attachment; filename="certificate_{isrc}.json"). The certificate document contains the track's canonical JSON, record hash, Merkle proof, and certification metadata.

---

GET /api/v1/certifications/{catalog_id}/report

Download the full catalogue certification report as a JSON file.

Path parameters

Parameter	Type	Description
catalog_id	string	Catalogue identifier.

Response

Returns a JSON file download (Content-Disposition: attachment; filename="catalog_report_{catalog_id}.json"). The report includes all certified tracks, batch metadata, aggregate statistics, and blockchain anchor details.

---

GET /api/v1/certifications/{catalog_id}/chain-of-title

Download the chain of title export for a catalogue.

Path parameters

Parameter	Type	Description
catalog_id	string	Catalogue identifier.

Response

Returns a JSON file download (Content-Disposition: attachment; filename="chain_of_title_{catalog_id}.json"). Contains the rights chain evidence for all certified tracks in the catalogue.

---

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

Download the complete proof bundle as a self-contained ZIP archive. This archive contains everything needed for independent, offline verification.

Path parameters

Parameter	Type	Description
catalog_id	string	Catalogue identifier.

Response

Returns a ZIP file download (Content-Disposition: attachment; filename="proof_bundle_{catalog_id}.zip"). See Glossary: Proof Bundle for contents.

---

GET /api/v1/certifications/{catalog_id}/{isrc}

Return the current certification status for a specific track.

Path parameters

Parameter	Type	Description
catalog_id	string	Catalogue identifier.
isrc	string	ISRC of the track.

Response body

{
  "isrc": "GBAYE0100538",
  "record_hash": "a1b2c3d4e5f6...64 hex characters",
  "canonical_json": "{...}",
  "certification_version": "1.0",
  "title": "The Wicker Man",
  "artist": "Iron Maiden",
  "iswc": "T-010.466.720-3",
  "writer_count": 3,
  "certified_at": "2026-01-15T14:30:00Z",
  "merkle_root": "e7f8a9b0c1d2...64 hex characters",
  "batch_status": "confirmed",
  "anchors": [
    {
      "chain": "bitcoin",
      "status": "confirmed",
      "tx_id": "3a1b2c3d...",
      "block_number": 879234,
      "block_timestamp": "2026-01-15T15:42:00Z"
    }
  ]
}

Field	Type	Description
isrc	string	The track's ISRC.
record_hash	string	SHA-256 hash of the canonical JSON (64 hex characters).
canonical_json	string | null	The canonical JSON used for certification.
certification_version	string | null	Schema version.
title	string | null	Track title.
artist	string | null	Primary artist name.
iswc	string | null	Primary ISWC.
writer_count	integer | null	Number of credited writers.
certified_at	string | null	Certification timestamp (ISO 8601).
merkle_root	string | null	Batch Merkle root.
batch_status	string | null	Status of the parent batch.
anchors	array	Blockchain anchors.

---

GET /api/v1/certifications/{catalog_id}

Return a high-level certification summary for a catalogue.

Path parameters

Parameter	Type	Description
catalog_id	string	Catalogue identifier.

Response body

{
  "catalog_id": "cat_01HZ...",
  "latest_batch_id": "batch_01HZ...",
  "latest_batch_status": "confirmed",
  "merkle_root": "e7f8a9b0c1d2...64 hex characters",
  "certified_track_count": 138,
  "total_golden_records": 138,
  "certified_at": "2026-01-15T14:30:00Z"
}

Field	Type	Description
catalog_id	string	Catalogue identifier.
latest_batch_id	string | null	Most recent batch ID. null if never certified.
latest_batch_status	string | null	Status of the latest batch.
merkle_root	string | null	Merkle root of the latest batch.
certified_track_count	integer	Number of currently certified tracks.
total_golden_records	integer	Total Golden Records in the latest batch.
certified_at	string | null	When the latest batch was certified.

---

Admin endpoint

POST /api/v1/certifications/{catalog_id}/certify

Trigger the full certification workflow for a catalogue. This is an administrative operation that fetches Golden Records, canonicalises them, constructs the Merkle tree, stores certifications, and submits the Merkle root for blockchain anchoring.

Authentication: Admin-only (requires admin role via Clerk).

Path parameters

Parameter	Type	Description
catalog_id	string	Catalogue identifier.

Response body

{
  "batch_id": "batch_01HZ...",
  "merkle_root": "e7f8a9b0c1d2...64 hex characters",
  "track_count": 142,
  "golden_record_count": 138,
  "status": "certified",
  "certifications": [
    {
      "isrc": "GBAYE0100538",
      "record_hash": "a1b2c3d4..."
    }
  ],
  "anchor_status": {
    "submitted": true,
    "calendar_response": "..."
  }
}

Field	Type	Description
batch_id	string	Newly created batch identifier.
merkle_root	string	Merkle root of the certification tree.
track_count	integer	Total tracks in the catalogue.
golden_record_count	integer	Tracks that qualified as Golden Records.
status	string	Initial batch status (typically "certified").
certifications	array	List of individual track certifications created.
anchor_status	object	Status of the OpenTimestamps submission.

Error responses

Status	Condition
400	No Golden Records found, or certification prerequisites not met.
401	Not authenticated.
403	User does not have admin role.
404	Catalogue not found.