Concepts
Evidence and content-addressed snapshots
Every answer carries a reference to the raw bytes behind it. Derived conclusions can be recomputed; the raw data cannot be rewritten.
An answer you cannot re-derive is an opinion. The API is built so that every answer resolves to the bytes it came from.
Snapshot references
Wherever the API reports something an upstream source said, it returns a SnapshotRef rather than a bare boolean.
cas:sha256:EXAMPLE00000000000000000000000000000000000000000000000000000000The reference is content-addressed. Snapshots are append-only and version-locked, so a reference resolves to the same bytes forever. Derived conclusions can be recomputed; the raw data behind them cannot be rewritten — including by us.
They appear as snapshot_ref on each LayerAHit, raw_ref on each VendorResult and on reasons that came from a vendor, and evidence_ref on exposure matches, revocations, and decisions.
The evidence bundle
GET /v1/decisions/{decision_id}/evidence returns the bundle for one decision as a ZIP.
manifest.json decision fields, evidence_hash, and verification instructions
layer_a/*.json raw response snapshots from each authoritative list source
layer_b/*.json raw vendor response bodies, subject to vendor licence terms
rule/{rule_version}.json
chain/{tx_hash}.json
report.pdfevidence_hash in manifest.json lets you verify the bundle independently, without trusting us.
Where a vendor’s licence does not permit redistribution of its raw response, layer_b/ contains a call record summary plus the vendor name and list version instead of the raw body. The bundle states which form it used, so a missing raw body is visible rather than silent.
One decision per request. There is no batch or date-range export of evidence, and no parameter that produces one.
Decision records
A decision record is append-only. decision_id identifies it, and it is never updated or deleted. rule_version records which version of your rule set produced it — rule versions are stored, two-person reviewed, and reproducible, so a past decision can be replayed against the rules that were actually in force at the time, not against today’s.
Keep decision_id next to your ledger entry. It is the join key between “we credited this” and “here is why, and here are the bytes”.
No bulk export
The rule is not a rate limit dressed up. There is no endpoint, parameter, or format that dumps enforcement data in a non-terminal stage — not on /v1/exposure, which is a change feed with a hard limit cap, and not on evidence, which is one decision at a time.