API Reference

REST v1.0

Programmatically verify records against the BitSeal ledger. Our API is designed for high-availability auditing.

INFO

The /verify endpoint is currently public and does not require authentication for basic rate limits (100 req/min). Enterprise keys will be required for higher throughput.

Client Libraries

BitSeal Python Core

The official Python SDK handles hashing, local sealing, and API interaction automatically. We strongly recommend using the SDK over raw API calls for large files.

View on GitHub

POST

/api/seal

Request Body (JSON)

root_hash

RequiredThe 64-character hex string of the file's Merkle Root.

filename

Original filename (stored in metadata).

size_bytes

File size in bytes.

Response Fields

seal_idUnique ID (e.g. "seal_...")

signatureEd25519 Hex Signature

pdf_base64Certificate PDF file

# Create a new Seal

curl -X POST https://bitseal.orygn.tech/api/seal \
-H "Content-Type: application/json" \
-d '{"root_hash": "a1b2...", "filename": "doc.pdf"}'

# 200 OK Response

{
  "success": true,
  "seal_id": "seal_8x9d...",
  "signature": "f3e1...",
  "pdf_base64": "JVBERi0xLjQK..."
}

GET

/api/verify?root={hash}

Query Parameters

root

The 64-character hex string (SHA256 or BLAKE3) of the file root.

Response Fields

validboolean

timestampISO 8601 Date

signerDID String

Status Codes

200Record found

404Record not found (Unsealed)

429Rate limit exceeded

# Example Request

curl "https://bitseal.orygn.tech/api/verify?root=a1b2..."

# 200 OK Response

{
  "valid": true,
  "found": true,
  "data": {
    "hash": "a1b2c3...",
    "timestamp": "2026-01-15T10:30:00Z",
    "signer_id": "did:bitseal:auth:primary",
    "metadata": {
        "verified_size": 1048576,
        "engine": "blake3-merkle"
    }
  }
}

# 404 Not Found

{
  "valid": false,
  "found": false,
  "error": "No seal found for hash a1b2..."
}

Verification