# CertiSigma API

> CertiSigma API v2.0.0 — 
> Base URL: https://api.certisigma.ch

Enterprise-grade cryptographic attestation and verification API.

## What is CertiSigma?

CertiSigma is a **zero-knowledge cryptographic attestation service**. You send a SHA-256 hash of any document or data — never the data itself — and CertiSigma returns a tamper-proof, legally admissible proof of existence with a precise timestamp. The original data never leaves your systems.

## Three-Tier Timestamping

Every attestation is progressively upgraded through three independent trust tiers:

**T0** is immediate: your attestation is signed with an ECDSA P-256 key upon creation. **T1** groups attestations into Merkle trees and timestamps the root with a qualified RFC 3161 TSA. **T2** anchors daily roots to the Bitcoin blockchain via OpenTimestamps for immutable public proof.

## API Endpoints

### Info

Service status, health checks, and public statistics. Use `GET /info` to discover enabled features and API version. `GET /healthz` is designed for monitoring probes (returns 200 when healthy, 503 otherwise). `GET /stats` returns aggregate attestation counts.

- `GET /info` — Get API information
- `GET /healthz` — Health check
- `GET /stats` — Public attestation statistics
- `GET /v1/info` — Get API information
- `GET /v1/healthz` — Health check
- `GET /v1/stats` — Public attestation statistics

### Attestation

Register SHA-256 hashes with cryptographic timestamping.

- `POST /attest` — Attest a SHA-256 hash
- `POST /attest/batch` — Batch attest multiple hashes
- `POST /v1/attest` — Attest a SHA-256 hash
- `POST /v1/attest/batch` — Batch attest multiple hashes

### Verification

Verify whether a hash has been previously attested. **Public endpoints — no authentication required.**

- `POST /verify` — Verify a hash attestation
- `POST /verify/batch` — Batch verify multiple hashes
- `POST /v1/verify` — Verify a hash attestation
- `POST /v1/verify/batch` — Batch verify multiple hashes

### Lookup

Retrieve attestation details by ID. Returns cryptographic proof only (hash, timestamp, signature, format version, signing key ID). Per-tenant metadata (source, extra_data) is not exposed on public lookup — use authenticated endpoints (POST /verify with API key, PATCH /attestation/{id}/metadata) for claim data.

- `GET /attestation/{attestation_id}` — Get attestation by ID (public — cryptographic proof only)
- `GET /v1/attestation/{attestation_id}` — Get attestation by ID (public — cryptographic proof only)

### T1/T2 Upgrade

Access cryptographic proofs across all trust tiers.

- `GET /attestation/{attestation_id}/status` — Get attestation trust tier status
- `GET /attestation/{attestation_id}/signature` — Get ECDSA signature
- `GET /attestation/{attestation_id}/tsa` — Get RFC 3161 TSA timestamp
- `GET /attestation/{attestation_id}/tsa/details` — Get parsed TSA token details
- `GET /attestation/{attestation_id}/merkle` — Get Merkle inclusion proof
- `GET /attestation/{attestation_id}/ots` — Get Bitcoin anchor data
- `GET /attestation/{attestation_id}/ots/proof` — Download raw OTS proof file
- `GET /v1/attestation/{attestation_id}/status` — Get attestation trust tier status
- `GET /v1/attestation/{attestation_id}/signature` — Get ECDSA signature
- `GET /v1/attestation/{attestation_id}/tsa` — Get RFC 3161 TSA timestamp
- `GET /v1/attestation/{attestation_id}/tsa/details` — Get parsed TSA token details
- `GET /v1/attestation/{attestation_id}/merkle` — Get Merkle inclusion proof
- `GET /v1/attestation/{attestation_id}/ots` — Get Bitcoin anchor data
- `GET /v1/attestation/{attestation_id}/ots/proof` — Download raw OTS proof file

### Evidence

Self-contained cryptographic evidence bundles for offline and forensic verification.

- `GET /attestation/{attestation_id}/evidence` — Get full cryptographic evidence bundle
- `GET /v1/attestation/{attestation_id}/evidence` — Get full cryptographic evidence bundle

### Keys

Public signing keys (ECDSA P-256) for independent client-side verification.

- `GET /keys` — List public signing keys
- `GET /keys/{key_id}` — Get public key by ID
- `GET /v1/keys` — List public signing keys
- `GET /v1/keys/{key_id}` — Get public key by ID

### Webhooks

Register webhook endpoints to receive real-time notifications when attestations are upgraded to T1 or T2.

- `POST /webhook/register` — Register a webhook
- `GET /webhooks` — List webhooks
- `DELETE /webhook/{webhook_id}` — Delete a webhook
- `GET /webhook/{webhook_id}/deliveries` — List webhook delivery history
- `POST /v1/webhook/register` — Register a webhook
- `GET /v1/webhooks` — List webhooks
- `DELETE /v1/webhook/{webhook_id}` — Delete a webhook
- `GET /v1/webhook/{webhook_id}/deliveries` — List webhook delivery history

### Metadata

Update or soft-delete per-API-key claim metadata on attestations.

- `GET /attestation/{attestation_id}/metadata` — Read claim metadata for an attestation
- `PATCH /attestation/{attestation_id}/metadata` — Update claim metadata on an attestation
- `GET /v1/attestation/{attestation_id}/metadata` — Read claim metadata for an attestation
- `PATCH /v1/attestation/{attestation_id}/metadata` — Update claim metadata on an attestation

### Brand

White-label brand configuration for custom verification pages. Retrieve brand settings (logo, colors, display name) by slug for embedding CertiSigma verification in your own branded interface.

- `GET /brand/{slug}` — Get brand configuration

## Resources

- [API Reference](https://developers.certisigma.ch/): Interactive API documentation with try-it-out
- [OpenAPI Spec](https://developers.certisigma.ch/openapi.json): Machine-readable OpenAPI 3.1 specification
- [Postman Collection](https://developers.certisigma.ch/postman.json): Import directly into Postman

## Authentication

All attestation and webhook endpoints require a Bearer token:
```
Authorization: Bearer cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
Verification and lookup endpoints are public (no auth required).

## SDKs

```bash
pip install certisigma          # Python
npm install @certisigma/sdk     # JavaScript
```