Core Concepts

Understand the key concepts behind Blanc — reviews, criteria, attestations, and verification.

Reviews

A review is a session where a human examines a document. Each review tracks:

Document hash — SHA-256 hash of the content being reviewed, ensuring integrity. You can provide document_content and the server computes the hash, or supply a pre-computed document_hash for privacy.
Criteria profile — The set of requirements the reviewer must meet
Status — pending → active → completed (or expired)
Review token — A short-lived token for the browser SDK to authenticate

Reviews expire after 24 hours if not completed.

Criteria profiles

A criteria profile defines what a reviewer must do to satisfy the review. Profiles are tenant-scoped and reusable.

Requirement	Description
`minTimeSeconds`	Minimum time the reviewer must spend reading
`fullScroll`	Whether the reviewer must scroll through the entire document (>= 95%)
`requireComment`	Whether a comment is mandatory
`presenceVerification`	Whether the reviewer's physical presence must be confirmed
`sectionsToAcknowledge`	Specific sections the reviewer must explicitly acknowledge

Profile types: medical, legal, financial, general, custom.

Evidence

When a reviewer completes their review, evidence is collected:

{
  "timeSpentSeconds": 180,
  "scrollPercentage": 98.5,
  "presenceVerified": true,
  "sectionsAcknowledged": ["diagnosis", "treatment_plan", "risks"],
  "comment": "All sections reviewed and verified.",
  "completedAt": "2026-03-15T12:05:00Z"
}

The evidence is validated against the criteria profile before an attestation is issued.

Attestations

An attestation is the cryptographic proof that a human completed the review. It contains:

Evidence hash — SHA-256 of the canonical JSON evidence
Signature — ed25519:{hash} derived from the document hash, evidence hash, and timestamp
Document hash — Links the attestation back to the original content

Attestations are immutable once issued.

Verification

Anyone can verify an attestation via the public /api/v1/attestations/:id/verify endpoint. Verification re-derives the signature from stored data and confirms:

Signature valid — The re-computed signature matches the stored one
Hash valid — The re-computed evidence hash matches

If both checks pass, the attestation is confirmed as tamper-proof.

Actions

An action is a structured agent tool call submitted for human approval before execution. Actions are the building block of human-in-the-loop (HITL) workflows in Blanc.

Each action contains:

Action type — A string identifying the operation (e.g. bank_transfer, deployment)
Action params — A structured object with the operation's parameters
Risk level — low, medium, high, or critical (visual indicator on the review page)
Callback URL — Optional webhook endpoint for receiving the decision

How actions differ from document reviews

	Document Reviews	Actions
Input	Markdown/text content with a document hash	Structured `action_type` + `action_params` object
Decision	Implicit approval (attestation = reviewed)	Explicit `approved` or `rejected` decision
Webhook	Not supported	Optional `callback_url` for decision delivery
Use case	Proving a human read and engaged with AI output	Gating agent execution behind human approval

Data model

Under the hood, actions are stored as reviews with is_action = true. The same reviews table, criteria profiles, and attestation pipeline are used. This means:

Actions share the same free tier quota (50/month combined)
The same POST /api/v1/reviews/:id/attestation endpoint handles both — with an additional required decision field for actions
verify-attestation works identically for both

The dedicated /api/v1/actions endpoints are convenience wrappers that set the action-specific fields and filter responses to only return actions.

Tenant isolation

All data is scoped to a tenant. API keys, reviews, attestations, criteria profiles, and members are all isolated per tenant. This ensures multi-tenant deployments keep data completely separated.

Core Concepts

On this page