API reference

POST /v1/receiptsREST#

Mirror one signed receipt. Idempotent on action_hash — a re-push of the same receipt returns the existing row, never a second one. Scope receipts:write (SDK plane).

POST /v1/receipts

Parameters

receiptActionReceiptrequired

The full signed receipt, wrapped in a { receipt } body. See the receipt schema for every field.

supersedes_action_hashstring?

Set only when finalizing an approval: a freshly assembled L1 supersedes the suspended L0 entry’s action_hash it was built from.

ReturnsReceiptPushResponse

{ status, entry_hash, seq }. entry_hashechoes the receipt’s own action_hash; seqis the mirror’s per-org append position.

Example

curl https://api.heso.ca/v1/receipts \
  -H "x-api-key: $HESO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "receipt": { /* full signed ActionReceipt */ } }'

status is one of:

There is no batch route; the SDK’s pushReceipts loops over this endpoint in order. A receipt that fails re-verification returns 409 (hash or signature mismatch) or 422 (missing or non-object content).

GET /v1/policy/pullREST#

Fetch the org’s active policy bundle. Scope policy:read (SDK plane).

GET /v1/policy/pull

ReturnsPolicyPullResponse

A PolicyPullResponse with the fields below.

Example

curl https://api.heso.ca/v1/policy/pull \
  -H "x-api-key: $HESO_API_KEY"

The response shape:

POST /v1/policyREST#

Deploy a new policy and activate it. Validated (parse + dangerous-lane floor) before any write. Dashboard plane (session JWT, manager+).

POST /v1/policy

Parameters

tomlstringrequired

The full policy TOML to deploy. See Policy for the rule format.

expected_policy_hashstring?

Optimistic concurrency: if set and it no longer matches the active pin, the deploy is refused 409 (another manager moved the policy first).

ReturnsPolicyPullResponse

A PolicyPullResponse for the newly activated policy (same shape as the pull above).

Example

curl https://api.heso.ca/v1/policy \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "toml": "[[rule]]\nid = \"...\"\n..." }'

A bad parse returns 422; a floor bypass attempt returns 409. Same TOML deploys to the same id and hash, so a re-deploy is idempotent.

POST /v1/approvalsREST#

Open (or idempotently re-open) a pending approval for a suspended action. Scope approvals:write (SDK plane).

POST /v1/approvals

Parameters

action_hashstringrequired

The action_hash of the suspended action this approval gates.

rule_idstring?

The policy rule that gated the action. Binds the scope the approver token must cover.

thresholdnumber?= 1

The k in a k-of-n quorum. Defaults to a single approver.

workflow, accountstring?

Optional display context carried into the approval queue.

ReturnsApprovalView

An ApprovalView: { approval_id, action_hash, status, threshold, approved_count, resolved_at }. status starts pending. HTTP 201.

Example

curl https://api.heso.ca/v1/approvals \
  -H "x-api-key: $HESO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action_hash": "<hex>", "rule_id": "pay.large", "threshold": 1 }'

One approval per (org, action_hash); re-opening the same action returns the existing approval.

GET /v1/approvals/{action_hash}REST#

Poll the current state of an approval, keyed by the action it gates.

GET /v1/approvals/{action_hash}

Parameters

action_hashstringrequired

Path parameter. The action_hash of the suspended action.

ReturnsApprovalView

An ApprovalView. status is pending, approved, or rejected.

Example

curl https://api.heso.ca/v1/approvals/<action_hash> \
  -H "x-api-key: $HESO_API_KEY"

The TypeScript SDK’s pollApproval and waitForApproval wrap this — reach for them instead of writing your own loop. When threshold is greater than one the approval is a k-of-n quorum: approved_count tracks how many distinct approvers have signed, and the assembled receipt is still L1, not a higher level.

POST /v1/approvals/{action_hash}/submit-tokenREST#

Submit a human-signed approval token to record one verified vote. Scope approvals:write (SDK plane).

POST /v1/approvals/{action_hash}/submit-token

Parameters

action_hashstringrequired

Path parameter. The action being approved.

token_b64stringrequired

The approval-token wire bytes, base64.

action_contentActionContentrequired

The receipt content the token signs over; the cloud re-derives the canonical bytes from it.

decisionstring?= approved

The human's declared intent: "approved" or "rejected".

ReturnsApprovalView

The updated ApprovalView. The cloud verifies the token against the org’s registered approver keys and records it as one vote — on a k-of-n quorum each of the threshold approvers submits their own token.

Example

curl https://api.heso.ca/v1/approvals/<action_hash>/submit-token \
  -H "x-api-key: $HESO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "token_b64": "…", "action_content": { /* receipt.content */ }, "decision": "approved" }'

GET /v1/audit/chainREST#

The org's tamper-evident receipt chain. Dashboard plane (session JWT, auditor+).

GET /v1/audit/chain

ReturnsAuditChain

An AuditChain: { head, size, entries }. Each entry links to the previous via a domain-separated BLAKE3 hash (chainHash), byte-identical to the browser verifier. Entries are newest-first; head is the last link.

Example

curl https://api.heso.ca/v1/audit/chain \
  -H "Authorization: Bearer $SESSION_JWT"

Flipping any leaf diverges every downstream link, so an offline re-derivation in the console is tamper-evident against this server-built chain. See Verification.

GET /v1/analyticsREST#

Headline governance counts for the dashboard. Dashboard plane (session JWT, viewer+).

GET /v1/analytics

ReturnsStatCounter[]

A StatCounter[] — each { key, label, value, display, spark }. Every number is derived from the org’s mirrored receipts and live approval queue.

Example

curl https://api.heso.ca/v1/analytics \
  -H "Authorization: Bearer $SESSION_JWT"