API Reference

1. Overview

All requests are made against https://proofledger.io. All responses are JSON, UTF-8 encoded. The API is versioned under /api/v1/; breaking changes will ship under a new version prefix.

The v1 API exposes three endpoints:

The API is intended for integrations where evidence is produced at scale — claims-intake systems, forensic pipelines, inspection apps, CMS watermarking hooks. For occasional single-file work, the web dashboard at dashboard.html is usually simpler.

2. Authentication & Access

a. API keys are BUSINESS-tier only

Proof submission and retrieval require an API key. Keys are issued from the Account page, and are only available to accounts on the BUSINESS plan. Free, Creator, Pro, and pay-as-you-go accounts cannot generate keys.

Upgrade at pricing.html or contact support@proofledger.io for enterprise volumes.

b. Creating a key

1. Sign in to your account.
2. Scroll to the API Keys section.
3. Enter a label (e.g. “Claims Intake”) and click Create Key.
4. Copy the key immediately — it is shown once and cannot be retrieved later.

Keys look like sk_ab12cd34_.... Store them as you would any secret: environment variable, secrets manager, or vault. Never commit keys to source control and never send them in query strings.

c. Sending the key

Pass the key as a Bearer token in the Authorization header:

Authorization: Bearer sk_ab12cd34_yourLongSecretHere

d. Revoking a key

Keys can be revoked at any time from the Account page. Revoked keys stop authenticating within a few seconds. If a key is compromised, revoke it immediately and issue a new one — past proofs remain valid regardless.

3. Submit a Proof

Request body

Example request

# 1. Hash the file locally — never send the file itself.
sha256sum site-inspection.pdf
# a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2

# 2. Submit the hash.
curl -X POST https://proofledger.io/api/v1/proof \
  -H "Authorization: Bearer sk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "sha256": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "filename": "site-inspection.pdf",
    "bitcoin_requested": true
  }'

Example response (201 Created)

{
  "id": 42,
  "sha256": "a1b2c3d4...f0a1b2",
  "filename": "site-inspection.pdf",
  "status": "approved",
  "created_at": "2026-04-21T14:22:03.000Z",
  "bitcoin_requested": true,
  "btc_payment_status": "INCLUDED",
  "duplicate_of": null,
  "certificate_url": "/cert/42",
  "verification_url": "/verify.html?hash=a1b2c3d4...f0a1b2"
}

The proof is accepted and queued for on-chain anchoring. Poll GET /api/v1/proof/:id or call the public verify endpoint to see the Polygon tx hash appear (typically under a minute) and Bitcoin txid appear (daily batched anchor).

4. Retrieve a Proof

Example request

curl https://proofledger.io/api/v1/proof/42 \
  -H "Authorization: Bearer sk_YOUR_KEY_HERE"

Example response

{
  "id": 42,
  "sha256": "a1b2c3d4...f0a1b2",
  "filename": "site-inspection.pdf",
  "status": "approved",
  "polygon_status": "anchored",
  "bitcoin_status": "pending",
  "evidence_readiness": "polygon-anchored",
  "created_at": "2026-04-21T14:22:03.000Z",
  "chain_tx": "0xabc123...",
  "chain_name": "polygon-mainnet",
  "bitcoin_txid": null,
  "bitcoin_anchor_status": "PENDING",
  "btc_merkle_root": null,
  "btc_payment_status": "INCLUDED",
  "public_cert_id": "pl_42_abc",
  "certificate_url": "/cert/42",
  "explorer_url": "https://polygonscan.com/tx/0xabc123...",
  "bitcoin_explorer_url": null
}

Status lifecycle

Immediately after submission, polygon_status is pending and chain_tx is null. The signer service picks up the job within ~30 seconds and broadcasts the transaction; once confirmed on-chain, polygon_status becomes anchored and chain_tx is populated. Bitcoin anchors follow a daily batch cycle, so bitcoin_status may remain pending for up to 24 hours even after payment.

5. Verify a Proof (Public)

Example request

curl "https://proofledger.io/api/v1/verify?hash=a1b2c3d4...f0a1b2"

Example response (found)

{
  "found": true,
  "proof": {
    "id": 42,
    "sha256": "a1b2c3d4...f0a1b2",
    "filename": "site-inspection.pdf",
    "created_at": "2026-04-21T14:22:03.000Z",
    "status": "approved",
    "polygon_status": "anchored",
    "bitcoin_status": "anchored",
    "chain_tx": "0xabc123...",
    "bitcoin_txid": "def456...",
    "public_cert_id": "pl_42_abc",
    "user_email": "a***@example.com"
  },
  "certificate_url": "/cert/42",
  "verification_url": "https://proofledger.io/verify.html?hash=...",
  "explorer_url": "https://polygonscan.com/tx/0xabc123...",
  "bitcoin_explorer_url": "https://blockstream.info/tx/def456..."
}

Example response (not found)

{
  "found": false,
  "sha256": "a1b2c3d4...f0a1b2"
}

6. Rate Limits & Quotas

Higher monthly caps are available on request — contact support@proofledger.io with your expected volume and use case.

7. Error Codes

All errors return a JSON body of the form {"error": "..."} with a human-readable message. Use the HTTP status code for programmatic decisions.

8. Independent Verification

In addition to the REST API, every ProofLedger proof can be verified entirely offline — without contacting ProofLedger's servers — using the verify-proof Python package.

pip install verify-proof

# Hash a file:
verify-proof hash ./evidence.pdf

# Verify against a proof JSON downloaded from ProofLedger:
verify-proof verify ./evidence.pdf --proof ./proof.json

This is the recommended path for court-submission workflows: a party challenging admissibility can run verify-proof on their own machine against the public blockchain record, independently of whether ProofLedger is online. Source: github.com/Fulcrum-Enterprises/verify-proof.

9. Support

For API questions, integration help, or to request a higher rate limit, contact:

ProofLedger LLC
support@proofledger.io

OpenAPI spec: /openapi.json · Related: Security & Hashing, Evidence Authentication, Evidence Policy