Developer Docs

HAPP Protocol Documentation

Everything you need to integrate cryptographic governance proof into your stack. REST APIs, proof types, verification, and more.

Quick Start API Reference Proof Types

Quick Start

Three steps to anchor your first governance proof.

Get Your API Key

Navigate to Settings → API Keys in your Verisum dashboard. Generate a key with prove:write scope. Available on the Verify plan.

Create a Proof

Call any /api/prove/* endpoint with your API key. Start with an attestation — it's the simplest proof type to test.

Verify It

Use the verification ID returned in the response. Call /api/public/verify or visit app.verisum.org/verify/{id} — no auth needed.

Authentication

All write endpoints require a Bearer token. The public verification endpoint requires no authentication.

Request Header

Authorization: Bearer YOUR_API_KEY

Generate a key: Settings → API Keys in your Verisum dashboard.

Required scope: prove:write for creating proofs, prove:read for reading your own proofs.

Rate limits: 100 requests/minute per key. Batch operations count as a single request.

Plan requirement: API access is available on the Verisum Verify plan.

Core Concepts

HAPP is built on three primitives that turn governance actions into verifiable, portable trust.

Anchor

Every governance event is serialised into a canonical JSON payload and hashed with SHA-256.
Hashes are batched into a Merkle tree (batch window: 60 seconds or 100 events, whichever comes first).
The Merkle root is written to an EVM-compatible blockchain as a single transaction, minimising gas costs.
Each individual proof can be verified via Merkle inclusion proof against the anchored root.

Attest

Attestations require a human in the loop. Automated systems can trigger governance events, but only authorised humans can sign attestations.
The attester reviews the evidence, adds their statement, and digitally signs. The signed attestation is then anchored via the Anchor primitive.
Attestations have a validity period (default 90 days). Expired attestations remain verifiable but are flagged as expired.

Exchange

Proofs can be shared with any external party using a single exchange request. No bilateral integration required.
The exchange itself is anchored — creating proof that specific governance evidence was shared with a specific party at a specific time.
Recipients verify proofs using the public /api/public/verify endpoint. No Verisum account needed.

Cryptographic Pipeline

event_data → SHA-256(payload) → Merkle(batch) → anchor(root, EVM) → VRF-{type}-{id}

Individual proofs are verified via Merkle inclusion proofs against the on-chain root. Full chain transaction details are included in every verification response.

API Reference

Base URL: https://app.verisum.org

POST/api/prove/approvals

Create Approval

Submit a governance decision for human approval. The decision is hashed, the approver signs off, and the proof is anchored on-chain. Returns a verification ID.

Request Body

Field	Type	Required	Description
`system_id`	string	Required	UUID of the AI system being governed
`decision_type`	string	Required	Type of decision: deployment, policy_change, model_update, data_access, config_change
`decision_summary`	string	Required	Human-readable description of the governance decision
`approver_email`	string	Required	Email of the designated human approver
`evidence`	object	Optional	Supporting evidence (assessment scores, policy references, risk ratings)
`expires_at`	ISO 8601	Optional	Expiry for the approval request (default: 7 days)

Response

Field	Type	Description
`id`	string	UUID of the approval record
`status`	string	pending_approval \| approved \| rejected
`verification_id`	string	VRF-APR-{id} — issued once approved and anchored
`approval_url`	string	URL for the approver to review and sign off

Example

const res = await fetch("https://app.verisum.org/api/prove/approvals", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    system_id: "sys_a1b2c3d4",
    decision_type: "deployment",
    decision_summary: "Approve v2.1 model deployment to production",
    approver_email: "cto@example.com",
    evidence: {
      trust_score: 78,
      risk_rating: "medium",
      assessment_id: "run_x9y8z7"
    }
  })
});

POST/api/prove/attestations

Issue Attestation

Create a signed attestation of compliance state. A human reviewer attests to the governance posture of a system or organisation. The attestation is hashed, Merkle-batched, and anchored.

Request Body

Field	Type	Required	Description
`target_type`	string	Required	What is being attested: organisation, system, or process
`target_id`	string	Required	UUID of the target entity
`attestation_type`	string	Required	compliance_state, risk_assessment, policy_alignment, incident_resolution
`statement`	string	Required	The attestation statement (what is being declared)
`attester_email`	string	Required	Email of the human attester
`evidence_refs`	string[]	Optional	UUIDs of supporting evidence (assessments, policies, incidents)
`valid_until`	ISO 8601	Optional	Attestation validity period (default: 90 days)

Response

Field	Type	Description
`id`	string	UUID of the attestation record
`verification_id`	string	VRF-ATT-{id} — issued once signed and anchored
`event_hash`	string	SHA-256 hash of the attestation payload
`anchored_at`	string	ISO 8601 timestamp of on-chain anchoring

Example

const res = await fetch("https://app.verisum.org/api/prove/attestations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    target_type: "organisation",
    target_id: "org_m4n5o6",
    attestation_type: "compliance_state",
    statement: "Organisation meets EU AI Act Article 9 requirements for risk management",
    attester_email: "dpo@example.com",
    evidence_refs: ["run_x9y8z7", "pol_a1b2c3"],
    valid_until: "2026-06-15T00:00:00Z"
  })
});

POST/api/prove/provenance

Record Provenance

Track AI system outputs with full provenance — model version, data sources, review status, and decision chain. Creates an auditable trail from input to output.

Request Body

Field	Type	Required	Description
`system_id`	string	Required	UUID of the AI system
`output_type`	string	Required	prediction, recommendation, classification, generation, decision
`model_version`	string	Required	Version identifier of the model that produced the output
`data_sources`	string[]	Required	Identifiers of input data sources used
`output_summary`	string	Required	Description of what was produced
`reviewer_email`	string	Optional	Human reviewer who validated the output
`review_status`	string	Optional	pending, approved, flagged, rejected

Response

Field	Type	Description
`id`	string	UUID of the provenance record
`verification_id`	string	VRF-PRV-{id} — issued once anchored
`event_hash`	string	SHA-256 hash of the provenance payload
`chain_of_custody`	object	Full input → model → output → review chain

Example

const res = await fetch("https://app.verisum.org/api/prove/provenance", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    system_id: "sys_a1b2c3d4",
    output_type: "recommendation",
    model_version: "gpt-4o-2026-03",
    data_sources: ["customer_db_v3", "product_catalog_q1"],
    output_summary: "Personalised product recommendations for 12,000 users",
    reviewer_email: "ml-lead@example.com",
    review_status: "approved"
  })
});

POST/api/prove/exchanges

Trust Exchange

Share anchored proofs with external parties — regulators, auditors, or supply chain partners. Creates a logged exchange record with recipient details and access controls.

Request Body

Field	Type	Required	Description
`proof_ids`	string[]	Required	Verification IDs of proofs to share (VRF-APR-, VRF-ATT-, etc.)
`recipient_org`	string	Required	Name of the receiving organisation
`recipient_email`	string	Required	Contact email for the recipient
`purpose`	string	Required	Why the proofs are being shared: audit, regulatory, due_diligence, partnership
`access_expires`	ISO 8601	Optional	When the shared access expires (default: 30 days)
`message`	string	Optional	Optional message to the recipient

Response

Field	Type	Description
`exchange_id`	string	UUID of the exchange record
`verification_id`	string	VRF-EXC-{id} — proof of the exchange itself
`share_url`	string	URL the recipient can use to view shared proofs
`proofs_included`	number	Count of proofs included in the exchange

Example

const res = await fetch("https://app.verisum.org/api/prove/exchanges", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    proof_ids: ["VRF-ATT-a1b2c3", "VRF-APR-d4e5f6"],
    recipient_org: "Financial Conduct Authority",
    recipient_email: "ai-governance@fca.org.uk",
    purpose: "regulatory",
    message: "Q1 2026 AI governance compliance evidence"
  })
});

POST/api/prove/incident-locks

Incident Lock

Forensic freeze of governance state at the moment of an AI incident. Captures assessment scores, active policies, system configuration, and governance posture as immutable evidence.

Request Body

Field	Type	Required	Description
`incident_id`	string	Required	UUID of the incident record from Verisum
`system_id`	string	Required	UUID of the affected AI system
`severity`	string	Required	critical, high, medium, low
`snapshot_scope`	string[]	Required	What to capture: assessments, policies, config, vendor_status, declarations
`locked_by`	string	Required	Email of the person initiating the forensic lock

Response

Field	Type	Description
`lock_id`	string	UUID of the incident lock record
`verification_id`	string	VRF-INC-{id} — proof of the frozen state
`event_hash`	string	SHA-256 hash of the entire governance snapshot
`snapshot`	object	The frozen governance state (scores, policies, config)

Example

const res = await fetch("https://app.verisum.org/api/prove/incident-locks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    incident_id: "inc_p7q8r9",
    system_id: "sys_a1b2c3d4",
    severity: "high",
    snapshot_scope: ["assessments", "policies", "config", "vendor_status"],
    locked_by: "incident-lead@example.com"
  })
});

GET/api/public/verifyNo auth required

Verify Proof

Public verification endpoint. No authentication required. Pass a verification ID to confirm the proof is authentic, unaltered, and anchored on-chain. Returns the proof metadata, chain transaction, and Merkle inclusion proof.

Query Parameters

Field	Type	Required	Description
`id`	string (query)	Required	The verification ID (e.g., VRF-APR-a1b2c3d4)

Response

Field	Type	Description
`valid`	boolean	Whether the proof is authentic and unaltered
`type`	string	Proof type: approval, attestation, provenance, exchange, incident_lock
`anchored_at`	string	ISO 8601 timestamp of on-chain anchoring
`chain_tx`	string	Transaction hash on the anchoring chain
`chain`	string	Network name (e.g., polygon, ethereum)
`event_hash`	string	SHA-256 hash of the original event
`merkle_proof`	string[]	Merkle inclusion proof for independent verification
`organisation`	string	Name of the organisation that created the proof

Example

// No authentication required
const res = await fetch(
  "https://app.verisum.org/api/public/verify?id=VRF-ATT-a1b2c3d4"
);
const proof = await res.json();

// {
//   valid: true,
//   type: "attestation",
//   anchored_at: "2026-03-15T14:22:00Z",
//   chain_tx: "0x7a3f...e91d",
//   chain: "polygon",
//   event_hash: "sha256:a1b2c3d4e5f6...",
//   merkle_proof: ["0x...", "0x...", "0x..."],
//   organisation: "Acme Corp"
// }

Proof Types

Every proof is identified by a verification ID with a type-specific prefix.

Type	VRF-ID Prefix	Description
Approval	`VRF-APR`	Human-approved governance decisions (deployments, policy changes, model updates)
Attestation	`VRF-ATT`	Signed compliance state declarations by authorised attesters
Provenance	`VRF-PRV`	AI output lineage — model version, data sources, review chain
Exchange	`VRF-EXC`	Cross-org proof sharing records with recipient and purpose
Incident Lock	`VRF-INC`	Forensic governance state snapshots at incident time

Verification ID Format

VRF-{TYPE}-{uuid}

Example: VRF-ATT-a1b2c3d4-e5f6-7890-abcd-ef1234567890

How Verification Works

Any HAPP proof can be independently verified without a Verisum account.

Hash Check

The original event payload is re-hashed and compared against the stored event_hash. Any alteration fails this check.

Merkle Inclusion

The event hash is verified against the Merkle root using the inclusion proof (sibling hashes). This confirms the proof was part of the anchored batch.

Chain Lookup

The Merkle root is verified against the on-chain transaction. This confirms the root was written to the blockchain at the claimed timestamp.

Verification Portal

Any HAPP proof can be verified in a browser:

https://app.verisum.org/verify/{verification-id}

No account required. No authentication. The portal shows the proof type, anchoring timestamp, chain transaction, and real-time verification status.

SDKs

Native SDKs for integrating HAPP directly into your governance workflows, CI/CD pipelines, and compliance tooling.

JS/TS

JavaScript / TypeScript

Full-featured SDK with TypeScript types, automatic retries, Merkle proof validation, and webhook support.

npm install @verisum/happ-sdk

Coming Q3 2026

Python

Pythonic SDK with async support, pandas integration for batch operations, and built-in proof validation.

pip install verisum-happ

Coming Q3 2026

Ready to Anchor Your First Proof?

HAPP is available today on Verisum Verify. Get your API key and start proving governance in minutes.

Get Started with Verify Back to Protocol Overview