API Reference v1 Stable

The Veratum API lets you create, retrieve, and verify cryptographic audit receipts for AI decisions. Every receipt is signed, hash-chained, and independently verifiable — even offline.

Authentication

All requests require a Bearer token. API keys use the vrt_ prefix and are hashed (SHA-256) before storage — Veratum never stores your raw key.

# Include in every request header
Authorization: Bearer vrt_your_api_key_here

# Or set as environment variable
export VERATUM_API_KEY=vrt_your_api_key_here

Quickstart

Create your first audit receipt in under a minute. Install the SDK and emit a receipt after any AI decision.

from veratum import wrap
from openai import OpenAI

# One line — wrap your existing client
client = wrap(OpenAI())

# Use it exactly as before — receipts are created automatically
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Assess risk for applicant #12345"}]
)

# That's it. A cryptographic receipt was generated, hash-chained,
# and uploaded to your Veratum audit trail automatically.

import { wrap } from 'veratum'
import OpenAI from 'openai'

// One line — wrap your existing client
const openai = wrap(new OpenAI())

// Use it exactly as before — receipts are created automatically
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Assess risk for applicant #12345' }]
})

// That's it. A cryptographic receipt was generated, hash-chained,
// and uploaded to your Veratum audit trail automatically.

# Ingest a receipt directly via the API
curl -X POST https://causmjvexaztsmbmikem.supabase.co/functions/v1/ingest-receipts \
  -H "Authorization: Bearer vrt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "entry_hash": "a1b2c3d4...",
    "prev_hash": "0000...0000",
    "timestamp": "2026-04-05T14:32:01Z",
    "model": "gpt-4o",
    "sequence_no": 0
  }'

# Verify any receipt publicly (no auth needed)
curl https://causmjvexaztsmbmikem.supabase.co/functions/v1/verify-receipt?hash=a1b2c3d4...

Create Receipt

Emit a new cryptographic audit receipt. The receipt is signed with Ed25519, hash-chained to the previous entry, and optionally timestamped by a qualified TSA.

Request Body

Response

{
  "id": "recv_1h7x8q2n",
  "entry_hash": "sha256:a1b2c3d4e5f6...",
  "prev_hash": "sha256:9z8y7x6w5v4...",
  "sequence_no": 1847,
  "timestamp": "2026-04-04T14:32:01.847Z",
  "signature": "ed25519:Kx7mR3...",
  "chain_valid": true,
  "tsa_token": null,
  "credential": null
}

Get Receipt

Retrieve a single receipt by ID or entry hash. Returns the full receipt with chain position and verification status.

List Receipts

Paginated list of receipts with optional filters. Returns most recent first.

Response

{
  "data": [{ ...receipt }, { ...receipt }],
  "has_more": true,
  "next_cursor": "cur_a8b7c6d5",
  "total": 12847
}

Verify Receipt

Independently verify a receipt exists in a Veratum chain. Returns the receipt data, chain position, neighbors, and XRPL anchor status. No authentication required.

Response

{
  "verified": true,
  "receipt": {
    "entry_hash": "81ed3398...",
    "prev_hash": "00000000...",
    "sequence_no": 0,
    "timestamp": "2026-04-05T14:32:01Z",
    "model": "gpt-4o",
    "provider": "openai",
    "human_review_state": "none"
  },
  "chain": {
    "position": 0,
    "prev": null,
    "next": { "entry_hash": "a6791...", "sequence_no": 1 },
    "chain_linked": true
  },
  "anchor": null
}

Verify Chain

Verify the integrity of an entire chain segment. Checks that every receipt's prev_hash matches the preceding entry_hash, with no gaps or tampering.

Response

{
  "valid": true,
  "range": { "from": 0, "to": 12847 },
  "entries_checked": 12847,
  "merkle_root": "sha256:f8e7d6c5...",
  "verified_at": "2026-04-04T14:36:00.000Z"
}

Qualified Timestamps

Receipts on Pro plans and above can include RFC 3161 qualified timestamps issued by a trusted third-party Time Stamping Authority. These provide legally admissible proof of when a receipt was created, independent of Veratum's infrastructure.

To request a qualified timestamp, set qualified_timestamp: true when creating a receipt. The TSA token is included in the response and can be verified independently using any RFC 3161-compliant tool.

Verifiable Credentials

Each receipt can optionally be wrapped as a W3C Verifiable Credential, making it interoperable with decentralized identity systems and portable across platforms.

Verifiable Credentials are issued automatically on Team plans and above. The credential format follows the W3C VC Data Model 2.0 specification, signed with Veratum's DID.

{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": ["VerifiableCredential", "AuditReceipt"],
  "issuer": "did:web:veratum.ai",
  "credentialSubject": {
    "entry_hash": "sha256:a1b2c3...",
    "chain_valid": true,
    "timestamp": "2026-04-04T14:32:01.847Z"
  },
  "proof": { ...Ed25519Signature2020 }
}

Webhooks

Get notified in real-time when events happen in your audit chain. Configure webhook URLs from your dashboard settings.

Available Events

All webhook payloads include a X-Veratum-Signature header for verification. See the authentication section for signature validation details.

Bulk Operations

Create up to 1,000 receipts in a single request. Ideal for batch processing or migrating existing audit logs.

Python SDK

Install from PyPI. Same wrap() pattern as TypeScript — one line to add audit trails.

pip install veratum

from veratum import wrap
from openai import OpenAI

# Wrap your OpenAI client
client = wrap(OpenAI())

# Use exactly as before
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Screen this resume"}]
)
# Receipt auto-generated with SHA-256 hash chain

# Verify any receipt offline
from veratum import verify_receipt
result = verify_receipt(receipt)
assert result.valid

from veratum import wrap
from anthropic import Anthropic

# Works the same way with Anthropic
client = wrap(Anthropic())

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Review insurance claim #98765"}]
)
# Cryptographic receipt sealed and uploaded

TypeScript SDK

Install from npm. Fully typed, zero runtime dependencies. Works with OpenAI, Anthropic, or any LLM client.

npm install veratum

import { wrap } from 'veratum'
import OpenAI from 'openai'
import Anthropic from '@anthropic-ai/sdk'

// Wrap any AI client — receipts generated automatically
const openai = wrap(new OpenAI())
const anthropic = wrap(new Anthropic())

// Use exactly as before — zero code changes
const res = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Review this loan application' }]
})
// Receipt auto-created: hash-chained, SHA-256 sealed, uploaded

// Advanced: capture previews, add metadata, listen for receipts
import { VeratumClient } from 'veratum'

const client = new VeratumClient({ vertical: 'insurance' })
const ai = client.wrap(new OpenAI(), {
  capturePreview: true,
  onReceipt: (r) => console.log('Receipt:', r.entry_hash),
})

Go SDK

Go SDK coming soon. Contact us for early access.

Error Codes

The API uses standard HTTP status codes. Errors return a consistent JSON body.

{
  "error": {
    "code": "invalid_hash_format",
    "message": "prompt_hash must be prefixed with sha256:",
    "status": 400
  }
}

Rate Limits

Rate limits are applied per API key and vary by plan. Your current limits are available in the dashboard at app.veratum.ai/settings.

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1712253600

Changelog

v1.0.0 — April 2026

Initial stable release. Core receipt creation, verification, chain integrity, qualified timestamps, W3C Verifiable Credentials, Python and TypeScript SDKs.