API REFERENCE / V1

Evidence API

Record a workflow event, preserve its source references and checks, and verify the chain later. Keep project keys on your server; never ship them to a browser.

Limitations: a verified hash chain shows that records match the stored integrity data. It does not prove a source document is truthful or that an event occurred.

POST /api/public/v1/evidence

Create an evidence event

Authenticate with a project-scoped key and supply a unique idempotency key. Retries with the same key and payload return the original record; reusing a key with a different payload returns a conflict.

RequestJSON / HTTP

curl -X POST https://your-app.example/api/public/v1/evidence \
  -H 'Authorization: Bearer pl_live_YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: invoice-1042-attempt-1' \
  -d '{
    "event_type": "invoice.approved",
    "occurred_at": "2026-01-14T10:32:18Z",
    "source_references": [{
      "label": "Invoice record",
      "reference": "https://billing.example/invoices/1042",
      "claim_status": "source_provided"
    }],
    "input_metadata": { "invoice_id": "INV-1042" },
    "checks_performed": [{
      "name": "vendor_policy",
      "result": "passed",
      "independently_confirmed": false
    }],
    "outcome": { "status": "approved" }
  }'

Response

201 · CreatedJSON / HTTP

{
  "status": "created",
  "id": "a7d4…",
  "sequence": 1,
  "payload_hash": "c62a…",
  "previous_hash": null,
  "event_hash": "057b…",
  "created_at": "2026-01-14T10:32:19Z"
}

event_typeRequired · up to 80 characters

occurred_atRequired · ISO 8601 timestamp with timezone

source_referencesUp to 40 named source references

input_metadataUp to 80 fields; keep sensitive values out

checks_performedUp to 40 named checks and results

outcomeRequired · result details as an object

POST /api/public/v1/verify

Verify a project chain

Send the verify scope with a project API key. The key itself identifies its project; a caller-supplied project ID is not used to choose the tenant.

RequestJSON / HTTP

curl -X POST https://your-app.example/api/public/v1/verify \
  -H 'Authorization: Bearer pl_live_YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

ResponseJSON / HTTP

{
  "valid": true,
  "checked": 12,
  "failed_sequence": null,
  "chain_head_hash": "6a0d…",
  "verified_at": "2026-01-14T10:35:00Z"
}

INTEGRITY MODEL

A linked, write-once record

Evidence payloads are validated, stored, and hashed server-side using SHA-256.
Each record links its hash to the preceding event in a project sequence.
Finalized records cannot be edited or deleted through the app.
Requests use project-scoped API keys, idempotency, input limits, and a basic per-project minute counter.

The custom minute counter is an MVP safeguard with operational limitations; use dedicated rate-limiting infrastructure before relying on it for high-volume production workloads. The chain does not independently anchor hashes outside this database.

Go to your workspace