Phase 6 — API & Integration Documentation

This chapter explains Export APIs as controlled pathways for retrieving replay evidence, governance evidence, telemetry evidence, and investigation evidence from Zahlen.

Chapter Purpose

Export APIs allow operators, supervisors, auditors, analysts, and connected systems to retrieve structured evidence from Zahlen. These exports are not merely download conveniences. They are operational evidence interfaces.

The purpose of an export is to make a defined body of evidence portable, reviewable, auditable, and reusable without weakening tenant isolation or governance integrity. A well-designed export API should preserve the meaning of the source evidence, identify how the evidence was produced, and indicate whether the exported content is suitable for replay review, governance review, telemetry review, investigation review, or external reporting.

This chapter explains four important export categories: replay exports, governance exports, telemetry exports, and investigation exports. Each category has a different purpose and a different trust posture.

Operator Perspective An export should answer more than “can I download this?” It should answer “what evidence is being exported, what does it mean, how trustworthy is it, and what can I safely do with it?”

 

What is an Export API?

An Export API is a programmatic interface that returns structured evidence from Zahlen for downstream use.

An export may return JSON, CSV, document artifacts, investigation records, telemetry summaries, replay evidence, audit trails, or machine-readable operational datasets. The exact format depends on the purpose of the export and the audience consuming it.

In Zahlen, exports should be treated as governed outputs. This means each export should have a clear scope, clear field definitions, access-control boundaries, tenant-safety protections, and enough context for the exported evidence to be interpreted correctly outside the immediate dashboard where it was generated.

Export APIs are especially important for enterprise adoption because many organizations need to integrate operational evidence into internal data warehouses, compliance workflows, incident-management systems, executive reporting, customer-support workflows, or audit packages.

Why This Matters Export APIs turn Zahlen from a dashboard-only tool into an operational evidence system. They allow Zahlen findings to travel into enterprise workflows while preserving structure, context, and trust.

 

Export Scope and Evidence Boundaries

Export scope defines what evidence is included in an export. Evidence boundaries define what evidence must remain excluded.

This distinction is important because Zahlen may contain tenant-private data, replay evidence, issuer-health signals, platform telemetry, operational notes, incident records, and eventually public-safe ecosystem intelligence. Not every user or system should be able to export every type of evidence.

A safe export should define the tenant, time window, issuer cohort, event type, run identifier, incident identifier, governance context, and format before evidence leaves the platform.

Scope Element	Definition	Why It Matters
Tenant scope	The merchant, tenant, or operational boundary for the export.	Prevents cross-tenant evidence exposure.
Time window	The start and end period covered by the export.	Keeps exports reviewable and prevents ambiguous evidence ranges.
Issuer cohort	The issuer BIN, country, card brand, or issuer grouping included.	Allows users to understand which issuer behavior is represented.
Run identifier	The ingestion or analysis run associated with the evidence.	Supports reproducibility and artifact traceability.
Incident identifier	The incident or investigation case associated with the export.	Supports operational review and incident coordination.
Format	The representation of the export, such as JSON, CSV, or document artifact.	Ensures the export is usable by the intended consumer.

 

Replay Exports

A replay export is a structured package of evidence that allows historical conclusions to be reconstructed, reviewed, or compared across replay executions.

Replay is the process of reprocessing historical events through deterministic logic. A replay export should therefore preserve the evidence required to understand what was replayed, how it was ordered, which rules or evaluation version were used, and what result was produced.

Replay exports are important for governance because they help prove that a conclusion can be reconstructed. If Zahlen identified issuer degradation, replay exports help show the event evidence, replay context, and deterministic output that supported that conclusion.

Why Replay Exports Matter Replay exports provide evidence that Zahlen’s conclusions can be reconstructed. They support auditability, deterministic verification, and governance confidence.

 

Replay Export Field	Definition	Operator Interpretation
replay_id	The unique identifier of the replay operation.	Use this to reference the replay package in audit or investigation review.
replay_window_start	The beginning of the historical window being replayed.	Defines where replay evidence begins.
replay_window_end	The end of the historical window being replayed.	Defines where replay evidence ends.
event_count	The number of events included in the replay.	Helps assess whether the replay has enough evidence.
input_digest	A stable digest or fingerprint of the replay input evidence.	Helps verify that the replay input has not changed.
output_digest	A stable digest or fingerprint of the replay output.	Helps compare replay results across executions.
replay_status	The status of the replay, such as completed, failed, divergent, or partial.	Indicates whether the replay result is operationally usable.
divergence_reason	The explanation for any replay mismatch or divergence.	Guides investigation when replay does not reproduce expected results.

 

How Operators Should Use Replay Exports

Operators should use replay exports when a conclusion needs to be verified, reconstructed, challenged, or compared across time.

A replay export is especially useful when an incident has escalated, when governance review is required, when replay divergence appears, or when an operator needs to confirm that a current recommendation is based on reproducible evidence.

If the replay export shows a completed replay with matching input and output digests, the conclusion is stronger. If the replay export shows divergence, missing evidence, or partial replay, the operator should treat the conclusion as requiring further review before it supports governance action.

Replay Export Status	Meaning	Recommended Response
completed	Replay finished and produced a result.	Review whether the result matches expected evidence and conclusion.
matched	Replay reproduced the expected conclusion.	Treat the evidence as stronger and more governance-ready.
divergent	Replay produced a different result than expected.	Investigate event ordering, evidence completeness, or evaluation logic.
partial	Replay ran with incomplete evidence or constraints.	Use with caution and document limitations.
failed	Replay could not complete.	Do not rely on replay evidence until the failure is resolved.

 

Governance Exports

A governance export is a structured package of evidence used to support supervisory review, compliance review, escalation review, trust-domain review, or audit workflows.

Governance exports differ from ordinary data exports because they must preserve reasoning, accountability, and decision context. A governance export should explain not only what happened, but how the platform interpreted it and why a recommendation or decision was considered justified.

Governance exports may include confidence scores, confidence explanations, evidence lineage, replay validation status, operator actions, supervisor decisions, escalation status, policy checks, quarantine status, and audit trail records.

Governance Interpretation A governance export should make a decision reviewable. It should preserve the evidence, reasoning, confidence, lineage, and accountability required to understand why the platform or operator reached a conclusion.

 

Governance Export Component	Definition	Why It Matters
decision_id	The identifier of the recommendation, decision, or governance event.	Allows the decision to be referenced and reviewed.
confidence_score	The numeric or categorical confidence assigned to the conclusion.	Shows how strongly the evidence supports the recommendation.
confidence_reasoning	The explanation for the confidence level.	Prevents confidence from becoming an unexplained score.
evidence_lineage	The traceable path from source events to conclusion.	Supports auditability and accountability.
replay_status	The replay verification state of the evidence.	Shows whether the conclusion is reproducible.
policy_status	The status of relevant governance or trust-boundary checks.	Shows whether the conclusion satisfies governance requirements.
operator_actions	Actions taken by operators or supervisors.	Connects evidence to human operational response.
audit_timestamp	The time the governance evidence was recorded or exported.	Supports audit trail continuity.

 

How Operators Should Use Governance Exports

Operators and supervisors should use governance exports when an issue requires formal review, cross-team explanation, escalation documentation, or compliance-friendly evidence preservation.

A governance export is appropriate when an incident is escalated, when a replay mismatch is reviewed, when an issuer degradation recommendation affects operational policy, when public-safe intelligence eligibility is evaluated, or when a supervisor needs an evidence package for later review.

Governance exports should be interpreted with attention to confidence and lineage. A high-confidence export with complete lineage and replay validation is stronger than an export with partial evidence, missing lineage, or unresolved replay divergence.

Supervisor Practice Before using a governance export to support a major decision, confirm that the export includes confidence reasoning, replay status, evidence lineage, and policy status. These fields explain whether the decision is operationally defensible.

 

Telemetry Exports

A telemetry export is a structured package of platform-observation evidence that explains how Zahlen processed, enriched, monitored, or evaluated operational events.

Telemetry describes the behavior of the platform itself. It may include ingestion status, enrichment status, event counts, truth matching status, processing warnings, external enrichment results, watermark advancement, processing lag, worker health, platform event creation, and other operational signals.

Telemetry exports are important because they help operators understand evidence quality. A finding supported by many well-processed events may be interpreted differently from a finding based on sparse events, missing truth matches, failed enrichment, or incomplete telemetry.

Telemetry Export Field	Definition	Operator Interpretation
telemetry_event_count	The number of telemetry events associated with a run, signal, or workflow.	Shows how much platform-observation evidence exists.
truth_matches_found	The number of truth records matched during enrichment.	Indicates whether external or internal truth evidence supported the signal.
truth_confidence_band	The confidence band assigned to matched truth evidence.	Shows the strength of truth-linked enrichment.
external_status	The state of external enrichment or external validation.	NOT_RUN means external enrichment was not executed.
watermark_advanced	Whether the pipeline advanced its processing watermark.	Shows whether processing progressed through the event sequence.
processing_lag	The delay between event time and processing time.	Helps detect pipeline pressure or delayed evidence.
warning_count	The number of processing or validation warnings.	Indicates potential evidence-quality concerns.

 

How Operators Should Use Telemetry Exports

Operators should use telemetry exports to understand whether a finding was produced under healthy processing conditions.

If telemetry shows that external enrichment was not run, truth-linked confidence may be unavailable even when the underlying issuer-health signal is still useful. If telemetry shows missing matches, processing warnings, or lag, the operator should document those limitations before using the finding for escalation or governance decisions.

Telemetry exports are especially useful for troubleshooting. They help distinguish between a weak issuer signal and an incomplete processing context. They also help explain why fields such as truth_confidence_band, truth_matches_found, or external_status may show NONE, zero, or NOT_RUN.

Operator Note Telemetry does not replace issuer evidence. It explains the processing context around issuer evidence. Strong telemetry increases confidence that the platform processed the evidence correctly.

 

Investigation Exports

An investigation export is a structured evidence package connected to a specific operational investigation, incident, issuer cohort, alert, or action-queue item.

Investigation exports are designed for operator use. They should help an operator or supervisor understand what triggered the investigation, which issuer or cohort is involved, what evidence supports the case, which actions have been taken, which recommendations were generated, and what next step is appropriate.

An investigation export may include incident metadata, issuer identity, country, card brand, response-code behavior, recovery-rate evidence, telemetry context, replay evidence, timeline events, task status, assigned operator, escalation state, recommended action, and closure recommendation.

Why Investigation Exports Matter Investigation exports preserve the story of an operational case. They allow the case to be reviewed, transferred, escalated, closed, or audited without relying on dashboard memory.

 

Investigation Export Component	Definition	Why Operators Need It
incident_id	The identifier of the investigation or incident case.	Allows teams to reference the same case across workflows.
issuer_context	Issuer BIN, country, card brand, and cohort identity.	Explains which issuer behavior is under review.
trigger_summary	The alert or signal that caused the investigation.	Shows why the case exists.
timeline_events	The ordered sequence of relevant evidence and actions.	Helps operators understand what happened over time.
replay_evidence	Replay status, replay output, or replay validation context.	Shows whether the evidence is reconstructable.
telemetry_context	Processing and enrichment evidence associated with the case.	Shows whether the case has strong processing support.
recommended_action	The platform’s recommended operational response.	Guides next steps while preserving explainability.
operator_actions	Actions taken by human operators or supervisors.	Supports accountability and handoff.
resolution_status	The current case state, such as unresolved, recovered, closed, or watch.	Explains whether the case still requires action.

 

How Operators Should Use Investigation Exports

Operators should use investigation exports for handoffs, escalations, case reviews, supervisor summaries, and post-incident documentation.

An investigation export is especially helpful when the same issuer cohort appears in multiple surfaces. For example, the same issuer may appear in the dashboard, action queue, alerts table, incident workspace, replay view, and system health outputs. The investigation export gives the operator a consolidated evidence package.

Operators should review whether the export includes the trigger, evidence, timeline, replay status, telemetry context, and recommended action. If one of those elements is missing, the export may still be useful, but it should be treated as incomplete.

Export Formats

Export formats determine how evidence is represented outside Zahlen.

JSON is well suited for machine-readable integration because it preserves nested structure and metadata. CSV is useful for analysts and spreadsheet workflows, but it may flatten evidence and lose hierarchy. DOCX or PDF artifacts are useful for human-readable reporting, executive summaries, and audit packets. ZIP or bundle exports are useful when multiple related files must remain together.

Format	Best Use	Limitations
JSON	Machine-readable evidence, API integrations, nested operational records.	Less convenient for non-technical readers.
CSV	Spreadsheet review, tabular exports, analyst workflows.	May flatten context and lose nested lineage details.
DOCX	Human-readable operational documentation or report drafts.	Less ideal for automated ingestion.
PDF	Controlled sharing, executive review, audit packet presentation.	Less flexible for downstream data processing.
ZIP bundle	Multi-artifact exports containing evidence, summaries, records, and reports.	Requires clear manifest and versioning.

 

Export Authorization and Access Control

Export authorization determines who or what system is allowed to retrieve evidence from Zahlen.

Export access should be more restrictive than ordinary dashboard viewing because exports can move evidence outside the immediate application context. A user may be allowed to view a page but not export all underlying records. A system may be allowed to export telemetry but not tenant-private investigation records.

Access control should consider user role, tenant context, data classification, export type, export size, destination system, and governance sensitivity.

Security Principle Export APIs should be treated as evidence-release boundaries. They require strong authorization, tenant isolation, audit logging, and clear scope controls.

 

Access-Control Dimension	Definition	Why It Matters
User role	The permissions assigned to the requesting user or service.	Prevents unauthorized export of sensitive evidence.
Tenant context	The merchant or operational boundary associated with the request.	Protects cross-tenant isolation.
Export type	The category of evidence being exported.	Different export types may require different approval levels.
Data classification	The sensitivity of the exported evidence.	Helps control private, internal, governance, or public-safe data.
Audit logging	A durable record of who exported what and when.	Supports accountability and compliance review.

 

Export Auditability

Export auditability is the ability to prove what was exported, who requested it, when it was generated, what scope it covered, and which evidence version it represented.

Auditability is critical because exported evidence may be used outside Zahlen in compliance reviews, executive summaries, customer-support escalation, internal incident review, or external reporting.

Each export should ideally include export metadata. Export metadata is information about the export itself, such as export identifier, timestamp, requester, tenant scope, filters, format, evidence digest, and source data version.

Export Metadata	Definition	Purpose
export_id	A unique identifier for the export operation.	Allows the export to be referenced later.
exported_at	The timestamp when the export was generated.	Supports audit timeline reconstruction.
requested_by	The user or system that requested the export.	Supports accountability.
tenant_scope	The tenant or merchant boundary covered by the export.	Protects isolation and explains scope.
filters_applied	The parameters used to select evidence.	Explains why the export contains certain records.
evidence_digest	A fingerprint of the exported evidence.	Helps detect whether evidence changed after export.
format_version	The schema or export contract version.	Supports compatibility and future interpretation.

 

Public-Safe Export Considerations

Public-safe exports are exports designed for use outside private tenant environments without exposing merchant-specific, customer-specific, or raw payment-level data.

A public-safe export should include only aggregated, anonymized, threshold-compliant evidence. It should never allow a recipient to infer what happened at a specific merchant or with a small identifiable merchant set.

Public-safe export eligibility should be governed by minimum crowd thresholds, tenant-isolation rules, evidence suppression rules, and confidence explanation requirements.

Governance Requirement Public-safe exports must not answer “what happened at Merchant X?” They should only answer “what issuer behavior appears across sufficiently large anonymous cohorts?”

 

Export API Troubleshooting

Export API troubleshooting is the process of resolving errors related to access, scope, filters, data availability, format compatibility, and evidence integrity.

A failed export does not always mean the underlying system is unhealthy. It may mean the requester lacks permission, the selected time window contains no evidence, the export type requires replay validation, or public-safe thresholds were not met.

Symptom	Likely Cause	Recommended Fix
Export returns no records	The filters may be too narrow or no evidence exists for the selected scope.	Review time window, issuer filters, incident ID, and tenant scope.
Export is denied	The user or service lacks permission for that export type.	Confirm role, tenant context, and export authorization policy.
Replay export unavailable	Replay has not run or replay validation failed.	Run or review replay verification before exporting replay evidence.
Governance export incomplete	Evidence lineage, confidence reasoning, or policy status may be missing.	Review governance record completeness before relying on export.
Telemetry export shows NOT_RUN	External enrichment or truth matching was not executed.	Interpret the export as telemetry-only for that enrichment dimension.
Public-safe export suppressed	Minimum aggregation thresholds were not met.	Wait for additional cohort evidence or use tenant-private analysis instead.

 

Recommended Export Workflow

A recommended export workflow begins with purpose. The requester should identify whether the export is for replay verification, governance review, telemetry troubleshooting, investigation handoff, analyst review, or public-safe communication.

Next, the requester should define the scope. This includes tenant, time window, issuer cohort, incident, run, export format, and evidence sensitivity.

The requester should then confirm that the export includes the required metadata and evidence context. For replay exports, this means replay identity and validation status. For governance exports, this means confidence reasoning and lineage. For telemetry exports, this means processing and enrichment status. For investigation exports, this means trigger, timeline, recommended action, and resolution state.

Finally, the export should be stored or transmitted according to the organization’s data-handling policy. Sensitive exports should not be treated like ordinary reports.

Chapter Summary

Export APIs allow Zahlen evidence to move into enterprise workflows while preserving operational meaning.

Replay exports support deterministic reconstruction and replay verification. Governance exports support supervisory review, confidence reasoning, auditability, and accountability. Telemetry exports explain platform processing and evidence quality. Investigation exports preserve the operational story of an incident or issuer-cohort review.

Export APIs should be governed by strong scope definitions, tenant isolation, access control, audit metadata, evidence digests, and public-safe aggregation rules.

When designed correctly, Export APIs make Zahlen evidence portable without making it unsafe. They allow payment intelligence to support operations, governance, compliance, and enterprise reporting while preserving trust.