API Reference

01 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 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 is usually simpler.

02 Authentication & Access

Proof submission and retrieval require an API key. Keys are issued from the Account page, and are available to accounts on the Elevated (PRO) and Formal (BUSINESS) plans. Free, Creator, and pay-as-you-go accounts cannot generate keys.

PRO plans get rate-limited API access for prototyping and small-scale production. BUSINESS plans get higher rate limits and dedicated support for high-volume integrations.

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

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 or send them in query strings.

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

Authorization: Bearer sk_ab12cd34_yourLongSecretHere

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.

03 Submit a Proof

# 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
  }'

{
  "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": "PAID",
  "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 (typically under a minute) and Bitcoin txid (daily batched anchor).

04 Retrieve a Proof

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

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

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. Bitcoin anchors follow a daily batch cycle, so bitcoin_status may remain PENDING for up to 24 hours.

05 Verify a Proof Public

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

{
  "found": true,
  "proof": {
    "id": 42,
    "sha256": "a1b2c3d4...f0a1b2",
    "filename": "site-inspection.pdf",
    "created_at": "2026-04-21T14:22:03.000Z",
    "polygon_status": "ANCHORED",
    "bitcoin_status": "ANCHORED",
    "evidence_readiness": "READY_BITCOIN",
    "chain_tx": "0xabc123...",
    "bitcoin_txid": "def456...",
    "user_email": "a***@example.com"
  },
  "certificate_url": "/cert/42",
  "explorer_url": "https://polygonscan.com/tx/0xabc123...",
  "bitcoin_explorer_url": "https://blockstream.info/tx/def456..."
}

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

06 Rate Limits & Quotas

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

07 Error Codes

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

08 Independent Verification

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.

09 Support

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

ProofLedger LLC
support@proofledger.io

Related: FAQ & Support · Enterprise