Skip to main content
The system maintains a complete chain of custody for all data through provenance tracking and export integrity. This enables any party (including legal counsel, auditors, or courts) to verify the origin and handling of intelligence used in reports.

​
How lineage establishes chain of custody

Every record stores its full lineage. When you retrieve lineage via the API, the system returns:
  1. Origin: Where the record came from with origin_feature, origin_source_id, and source_details.
  2. Transform chain: Each transform that produced or enriched the record, with transform_name, connector_name, executed_at, and executed_by. This links data to the specific connector and user.
  3. Transitions: When data moved between features with from_feature, to_feature, trigger_type, and user_id.
  4. Field updates: Every modification to record fields, with field_path, old_value, new_value, source, and user_id.

​
Retrieving lineage

# Single record lineage (origin, transforms, transitions, updates)
curl "https://your-hostname/api/provenance/{id}/lineage" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Full ancestry chain from root to current record
curl "https://your-hostname/api/provenance/{id}/full-lineage?max_depth=50" \
  -H "Authorization: Bearer YOUR_TOKEN"
The full lineage response includes a chain (records from root to current) and a unified timeline of events.

​
Export integrity

When exporting a report to PDF with include_provenance: true, the export captures:
  • Exported at: UTC timestamp of export generation
  • Exported by: User ID who triggered the export
  • Data fingerprints: SHA-256 hash of each section’s data at export time
The fingerprints are embedded in the PDF. To verify integrity, recompute the SHA-256 of the same data; it should match the stored fingerprint. A mismatch indicates the data has been altered since export.

​
What the chain of custody proves

A complete lineage record establishes:
  • Where the data came from: Origin feature and source ID, with optional source details
  • How it was produced: Transform name, connector name, and who executed it
  • When each step occurred: Timestamps on origin, transforms, transitions, and updates
  • Who handled the data: created_by, executed_by, updated_by (with display names when available)
  • What changed: Field update history with old and new values
Together with export provenance (which records who exported the report and when, plus data fingerprints), this constitutes a complete chain of custody for the intelligence used in reports.

​
Sharing reports externally

When providing a report to a third party (legal counsel, regulator, court):
  1. Export the report to PDF with include_provenance: true
  2. Provide the PDF; the provenance section and fingerprints are embedded in the document
  3. The recipient can verify the export timestamp and exporter identity from the provenance section
  4. If the recipient has access to the source data, they can recompute the fingerprints to confirm the exported data matches what was in the report at export time