Skip to main contentCertyo Developer Portal

API Reference

The 15 public endpoints, grouped by purpose. All endpoints are under https://www.certyos.com and require the X-API-Key header.

Interactive Swagger UI
Prefer an interactive view with request/response schemas? The full OpenAPI spec is served at /swagger.
Open full Swagger UI

Record Ingestion

Submit records to Certyo for Merkle-tree batching and Polygon blockchain anchoring. All responses are 202 Accepted — anchoring happens asynchronously.

POST
/api/v1/records
Ingest a single record
Send one record for blockchain anchoring. Returns immediately with the record hash.
POST
/api/v1/records/bulk
Ingest up to 1000 records
Bulk ingest for high-throughput workloads. Each record is validated independently.
GET
/api/v1/records
Query ingested records
Filter by tenantId, database, collection, recordId, or time range. Returns record summaries.

Verification

Cryptographically prove that a record exists and has not been tampered with. Three verification modes let you verify from different starting points.

POST
/api/v1/verify/record
Verify by record + payload
Most common — provide the original payload and Certyo recomputes the hash, walks the Merkle proof, and checks against the on-chain root.
POST
/api/v1/verify/payload
Verify by payload hash
When you have a precomputed hash but not the original payload. Confirms the hash was anchored.
GET
/api/v1/verify/snapshot/{snapshotId}
Verify by snapshot ID
When you have the internal snapshot ID and want to check its on-chain anchoring status.
GET
/api/v1/verify/history
Verification audit trail
List all verification attempts for a tenant, with outcome and timestamp. Useful for compliance reporting.

Status & Lifecycle

Poll the anchoring status of records and snapshots. Use these endpoints to build your own anchoring dashboards or to confirm when a record has been committed to the blockchain.

GET
/api/v1/snapshots
Query snapshots
List snapshots by tenant, record ID, or status. Check onChainConfirmed to see if anchoring is complete.
GET
/api/v1/snapshots/{snapshotId}
Get snapshot details
Full details of a single snapshot including Merkle root and blockchain tx hash.
GET
/api/v1/snapshots/{snapshotId}/lifecycle
Get state transition history
Chronological log of state transitions (Ingested → PendingAnchor → Batched → Anchored). Useful for debugging stuck records.
POST
/api/v1/snapshots/{snapshotId}/retry
Force retry a failed snapshot
Manually trigger a retry for a snapshot stuck in Failed state. Automatic retries also run in the background.
GET
/api/v1/batches/{batchId}
Get batch metadata
Retrieve the Merkle root, record count, blockchain tx hash, and IPFS CID for a batch.
GET
/api/v1/timeline/record
Get full pipeline timeline
Event-by-event history of a record from ingestion through on-chain confirmation. Great for support tickets.

Audit & Compliance

Endpoints for auditors, compliance teams, and controlled evidence retrieval.

GET
/api/v1/audit/history
Tenant audit trail
All notable actions for a tenant — ingestions, verifications, retries, access grants. Used for SOC 2 and ISO 27001 evidence.
POST
/api/v1/evidence/retrieval-controls
Request evidence retrieval
Controlled access check for evidence retrieval. Confirms a caller has permission to fetch specific records based on tenant policies.

Authentication

All endpoints require the X-API-Key header:

X-API-Key: certyo_sk_live_abc123...

See the authentication guide for key management and rotation.

Response Status Codes

  • 200 OK — request succeeded (for GETs)
  • 202 Accepted — record queued for async processing (for POSTs to ingestion endpoints)
  • 400 Bad Request — invalid request shape or missing required fields
  • 401 Unauthorized — missing or invalid API key
  • 403 Forbidden — API key valid but not authorized for the requested tenant
  • 404 Not Found — resource doesn't exist (snapshot, batch, etc.)
  • 429 Too Many Requests — rate limit exceeded; back off and retry
  • 500 Internal Server Error — contact support with the X-Correlation-Id response header