Detection Audit
Per-entity provenance — why each entity was recognized and what happened to it
Activity Log
Per-workspace actions — who did what, and when
Detection Audit
Every detection produces an audit describing what analysis found in one document:Reviewer edits are not in the audit. They are the caller’s own input, applied
to the report before redaction, so an audit carries what analysis found as
amended rather than the amendments themselves. A redaction’s own review
audit is at
/workspaces/{workspaceId}/redactions/{redactionId}/review.Context
The context travels from analysis through to redaction, so the conditions an entity was recognized under are recorded alongside the finding:
The
codec records how the document was decoded — the entity offsets are
stored against that decode, and a differently-rendered second one would not
line up.
Entity Provenance
Each recognized entity carries anaudit — a hash-linked DAG of events
explaining how it reached its final state. Every event records a kind,
confidence, timestamp, source, parents, and a hash.
Because events carry
parents, the trail is a graph rather than a flat list.
A birth event has no parents, a normal step has one, and a fusion has several —
so you can trace a final entity back through every merge and reconciliation
that produced it. An entity’s effective confidence always equals that of its
most recent event.
Each event’s
hash folds its payload together with its parents’ hashes, so
any edit, reorder, insertion, or deletion of an earlier event breaks every
event downstream of it. Verification walks the DAG and reports the first
break.Redaction Events
Aredaction event records which operator ran (by name and version), the
matched_by rule that chose it, and the attribution the policy author
attached — the authority the change answers to, either a freeform label or a
formal citation. Where matched_by answers which rule fired, attribution
answers why the policy demanded it.
A reviewer’s decisions live on the same trail. A suppression is a manual
event on the entity’s audit, not a separate flag, so the record of a human
override sits in the same tamper-evident chain as the machine’s findings.
Exporting
Detection audits export in two formats for archiving:format defaults to csv — a zip of entities.csv, provenance.csv, and
reviews.csv — or pass json for a pretty-printed JSON file.
Activity Log
Separately from detection audits, each workspace records the actions taken within it:
Activity types are namespaced by subject —
document.created,
pipeline.detection.completed, pipeline.redaction.created,
connection.sync.failed, provider.updated, review.verified, and so on.
Filter by type (repeat the parameter for several), by actor, and by a
from / to date window.
Activity payloads store identifiers and parameters, not rendered sentences.
The client localizes the description from
type and its params, so the log
stays language-neutral and stable as wording changes.Review Trails
A review adds a third, human-facing record: a named discussion on a document with its own timeline of comments interleaved with lifecycle events —review.opened, review.renamed, detection.linked, redaction.linked,
assigned, unassigned, verified, and reopened.
reviewStatus is derived from those events rather than set by hand, so
the sign-off state and the trail that produced it cannot disagree.
Retention
Documents record their role, which drives retention scope:
Machine byproducts — detection audits, review audits, and enrichment
intermediates — are not documents; they are retained on their own scopes. A
pipeline may override the workspace baseline per scope with
retention,
setting auditLogs, intermediates, or redactedDocuments. Original
documents are ingested rather than produced by a pipeline, so they always
follow the workspace baseline.
For deployments where retention is governed internally, see
on-premise deployment.
Next Steps
Redaction Workflow
Where the audit fits in the detection lifecycle
API Reference
Audit and activity endpoints