CLARIXO Behavior Evidence Export API Integration Protocol

What this protocol is

A contract for post-behavior traceability, proof, and audit

This protocol defines the formal contract for CLARIXO Behavior Evidence Export API, including role, boundary, minimum evidence record, and integrity rule. It stays separate from runtime control infrastructure so teams can establish evidence export without first redesigning the live execution path.

Contract

Defines the evidence export role

Use this document to understand what the Behavior Evidence Export API is, what it is not, what the minimum record must contain, and how evidence integrity is defined in the contract.

Boundary

Does not take over runtime control

This protocol does not define routing, fallback control, guard enforcement, approval gating, or execution governance. It preserves evidence after execution, while runtime control responsibilities remain with CLARIXO Core Runtime API.

What this protocol governs

Standardize the outbound evidence export path

This protocol governs when an evidence event should be created, what the minimum record must contain, how the record should be normalized, and how basic integrity should be preserved through evidence_hash. It assumes that the source AI system still owns its own runtime execution path.

Position

Evidence plane, not control plane

The Behavior Evidence Export API sits on the enterprise-to-end-user evidence side. Its role begins after user-facing AI behavior has been formed or delivered.

Purpose

Preserve behavior for later review

The protocol exists to support traceability, dispute review, incident reconstruction, support escalation, audit preparation, and internal quality review without claiming execution control.

What this protocol does not govern

Keep evidence export separate from runtime governance

Not included

This protocol does not define model routing policy, provider fallback logic, approval workflow, runtime intervention, execution denial, commit-boundary governance, or source-system permission policy design.

Why that matters

An evidence export path helps explain behavior after execution. A runtime control layer helps govern behavior before or during execution. CLARIXO keeps those responsibilities separate on purpose.

Official distinction

This protocol does not define how to control AI execution. It defines how to preserve evidence of AI behavior after execution has already occurred.

Minimum API surface

Keep the first contract intentionally narrow

Write

POST /v1/evidence/events

Submit one normalized evidence event or an events array after the user-facing AI behavior has already occurred and the delivered path is known.

Read

GET /v1/evidence/events

Retrieve previously exported evidence events for filtering, review, reconstruction, support handling, and audit support.

Evidence event definition

Choose one meaningful user-facing behavior boundary

Under this protocol, one evidence event should describe one meaningful unit of user-facing AI behavior. In most systems, that means one completed assistant reply, recommendation, moderated output, transformed result, or operator-assisted final response.

Good boundary

One reviewable behavior unit

A good event boundary maps cleanly to a human review question and stays stable enough that later reviewers can reconstruct what happened without ambiguity.

Avoid drift

Do not over-expand the first contract

The protocol does not require every internal helper call to become an evidence event. It requires a stable, interpretable unit of user-facing behavior.

Minimum evidence record

Define one stable record contract before expanding scope

Identity

schema_version, project_id, application_id, event_id, session_id, and recorded_at should identify the record, the scope it belongs to, and the time at which the behavior record was finalized.

Behavior

user_ref, input_summary, and output_summary should preserve the user-facing behavior in a normalized, reviewable form without requiring evidence export to become a full raw-log warehouse.

Path and outcome

provider, model, route_path, fallback_used, guard_flags, confidence_signals, operator_action, final_status, metadata, and evidence_hash preserve how the delivered behavior was produced, how it was shaped, and how the core record can later be checked.

Field responsibility principles

Keep the record useful for later human review

Stable identity

project_id, application_id, event_id, and session_id should remain stable enough to support later lookup, grouping, and case reconstruction.

User-facing relevance

input_summary and output_summary should remain meaningful during later review, even without direct access to the original runtime trace.

Execution visibility

provider, model, route_path, and fallback_used should reflect the actual delivered path rather than an intended path that was never finally used.

Context admissibility metadata

When the source system can produce it, metadata.context_admissibility may carry a compact review-strengthening summary of context quality, including input binding, runtime source, runtime scope, pollution flags, clean context hash, and recomposition posture.

Responsibility and evidentiary strength

When an integration exports review-ready or EVIDE-compatible responsibility records, the protocol may also carry top-level fields such as closure_state, responsibility_declared, authority_consistency_status, handoff_eligible, evidentiary_strength, degradation_reason, trace_continuity_status, trace_reconstruction_status, attribution_validity, and attribution_strength.

Integrity rule

evidence_hash is part of the protocol contract

Hash algorithm

Use SHA-256 and return the result as sha256:<hex>.

Core fields

schema_version, project_id, application_id, event_id, session_id, recorded_at, user_ref, input_summary, output_summary, provider, model, route_path, fallback_used, guard_flags, and final_status.

Hash scope boundary

Responsibility fields, evidentiary-strength fields, and optional context admissibility metadata are supported for review and export carry-forward, but they are not part of the current evidence_hash canonical core.

Normalization

Use UTF-8, ISO 8601 timestamps, trimmed strings, booleans as true or false, sorted comma-joined arrays, and none for empty guard_flags.

Purpose

This is a practical record-integrity baseline. It is not positioned as a full chain-of-custody framework. Its purpose is to let later consumers verify that the core behavioral record still matches what was originally exported.

Evidence review surfaces

Separate exact evidence review from internal evidence observation

After completing Evidence API integration, a connected product should separate its internal evidence-facing surfaces into two distinct pages: Evidence Records and Internal Evidence Observation Window. These two surfaces should not be merged into a single page because they solve different review problems.

Evidence Records

Protected record-level query and review

Evidence Records is the protected record-level query and review surface. It is used for exact evidence lookup, record inspection, protected review, export preparation, and dispute or compliance follow-up.

Observation

Internal evidence visibility and triage

Internal Evidence Observation Window is the higher-level internal visibility and triage surface. It is used to help internal teams observe evidence activity before deciding which records require deeper review.

Recommended separation

A connected product should keep these two surfaces separate: Evidence Records = exact lookup and protected review. Internal Evidence Observation Window = visibility and triage. Observation shows what is happening. Records show exactly what happened.

Minimum contents

An Internal Evidence Observation Window should include a time-range selector such as 24h / 7d / 30d, total evidence event count, project identifier or application identifier, route-path distribution, final-status distribution, provider distribution, recent evidence events list, and optional links into the Evidence Records page.

Minimal query pattern

GET /v1/evidence/events?project_id=<project_id>&application_id=<application_id>&recorded_from=<iso8601>

Recommended observation fields

Recommended fields include recorded_at, event_id, session_id, route_path, final_status, provider, and aggregate counts and distributions. This surface should remain focused on visibility and triage rather than becoming the main export or deep-review page.

Expected outcome

When implemented correctly, Evidence Records becomes the internal evidence lookup and protected review surface, while Internal Evidence Observation Window becomes the internal monitoring and triage surface. Together, these two pages move a connected product from evidence existence to evidence usability.

Cross-link

Need the implementation document instead?

Use the Integration Manual for event definition, field mapping, payload normalization, submission timing, retrieval discipline, verification flow, and rollout guidance. Use the Evidence API page for product overview and live handler examples.

Open Integration Manual Back to Evidence API