Manual · Implementation, Verification, and Rollout

CLARIXO Behavior Evidence Export API Integration Manual

The implementation document for turning user-facing AI behavior into stable exportable evidence records.

Open Integration Protocol Back to Evidence API
What this manual helps you do

Turn the protocol into a working implementation path

This manual explains how to choose an evidence-event boundary, map required fields, normalize a payload, generate evidence_hash, submit records, retrieve them later, verify that the exported result is operationally useful, and roll the integration out in a stable way. It is the implementation document for evidence export only, not a runtime control or enforcement manual.

Build

Define one evidence event first

Start with one completed user-facing AI behavior and one stable event boundary rather than trying to export every internal intermediate state.

Verify

Close the first working loop

The minimum integration is complete when you can submit one evidence record, query it back, and confirm that a human reviewer can understand what happened.

Implementation objective

Preserve one meaningful behavior in a stable evidence form

A good first integration is not the one that exports the most data. It is the one that exports one stable, reviewable evidence record with the least ambiguity and enough context for later support, reconstruction, and audit work.

Target

One completed user-facing output

In most systems, the best starting point is one assistant answer, one generated explanation, one recommendation batch, one moderated output, or one operator-assisted final response.

Boundary

Do not confuse internal steps with evidence events

Avoid making every helper call an evidence event unless that call is itself the meaningful user-facing behavior being reviewed later.

Minimum integration path

Export after the behavior happens

Step 1

Complete the user-facing AI behavior

Let the enterprise system finish the user-visible response or result before exporting an evidence record, so the delivered path is already known.

Step 2

Normalize into an evidence payload

Map the event into stable fields such as project scope, application scope, event identity, summaries, provider, route path, fallback usage, outcome, and metadata.

Optional step

Attach context admissibility metadata

When the source system can identify input binding, runtime source, runtime scope, and context pollution signals, attach a review-strengthening metadata.context_admissibility summary before export.

Step 3

Generate evidence_hash

Generate a SHA-256 evidence hash from canonicalized core fields for practical record-integrity verification.

Step 4

Submit and retrieve

Write the evidence event to CLARIXO, then query it back by project, application, session, route, event, or time window to validate real review usefulness.

Required source mapping

Map each required field to a real upstream origin

Before writing the export path, map every required evidence field to a real data source in the application. This keeps exported records stable even while the source system continues to evolve.

Scope and identity
Map project_id, application_id, event_id, session_id, and recorded_at to stable source-system values that support later lookup and grouping. For write authorization, the submitted project_id must match the project bound to the supplied trial key.
Behavior summaries
Map input_summary and output_summary to short normalized descriptions that preserve the user-facing interaction without requiring full raw payload storage in exported records.
Delivered path
Map provider, model, route_path, fallback_used, guard_flags, confidence_signals, operator_action, and final_status to the actual delivered path rather than an intended path that never became the final outcome.
Minimum evidence payload

Keep the first payload stable and reviewable

{
  "schema_version": "v1",
  "project_id": "trial_proj_cec59281f5cfc093",
  "application_id": "tgtracing:assistant:customer_chat",
  "event_id": "evt_20260408_0001",
  "session_id": "sess_7c1f3b9d",
  "recorded_at": "2026-04-08T17:58:11Z",
  "user_ref": "user_anon_1024",
  "input_summary": "User asked whether a shared tracking link could reveal location without consent.",
  "output_summary": "Assistant explained that consent-based interaction is required and did not claim passive tracking.",
  "provider": "enterprise_app",
  "model": "gpt-4.1",
  "route_path": "direct",
  "fallback_used": false,
  "guard_flags": ["policy_boundary_explained"],
  "confidence_signals": {
    "answer_mode": "policy-aligned",
    "uncertainty_level": "low"
  },
  "operator_action": "none",
  "final_status": "delivered",
  "metadata": {
    "locale": "en",
    "record_origin": "manual_post",
    "runtime_scope": "openai_free",
    "runtime_source": "openai",
    "context_admissibility": {
      "schema_version": "context-admissibility-v1",
      "mode": "shadow",
      "overall_state": "admissible_shadow",
      "admitted_count": 8,
      "excluded_count": 0,
      "downgraded_count": 0,
      "needs_review_count": 0,
      "pollution_flags": [],
      "clean_context_hash": "sha256:examplecontexthexvalue",
      "recompose_strategy": "none_shadow_only"
    }
  },
  "evidence_hash": "sha256:examplehexvalue"
}
Normalization discipline

Normalize before export, not after confusion appears

Consistency first
Standardize timestamps into ISO 8601, trim strings, coerce booleans into true or false, and keep optional arrays and flags predictable.
Summaries over dumps
In many systems, input_summary and output_summary are more operationally useful than raw payload dumps because they are easier to review, more privacy-aware, and less affected by formatting noise.
Actual delivered path
The evidence record should describe the path that actually produced the delivered outcome, including real provider, real model, and whether fallback was used.
Hash generation

Generate evidence_hash from the protocol core fields

Use only the 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.
Normalize first
Use UTF-8, ISO 8601 timestamps, trimmed strings, booleans as true or false, sorted comma-joined arrays, and none for empty guard_flags.
Store the result
Hash with SHA-256 and store the output as sha256:<hex>.
Why this exists
The hash is a practical integrity check for the exported behavioral record. It helps answer whether the core evidence object still matches what was originally exported.
Verification loop

Do not stop at write success

A first integration is only truly usable when the team can write a known record, retrieve it through practical filters, and confirm that another human can understand what happened without relying on private internal context. If a write fails with a project mismatch, verify both the submitted project_id and the project bound to the supplied trial key.

Write one event
Submit one known evidence event with a stable event_id and enough reviewable content to recognize it later.
Query it back
Retrieve the record by event_id, project_id, application_id, session_id, route_path, or time window.
Confirm readability
Check that input_summary, output_summary, final_status, and evidence_hash are present and understandable to a human reviewer.
Confirm path truth
Verify that provider, model, route_path, and fallback_used reflect the actual delivered path rather than an intended path that changed before delivery.
Confirm review-ready fields when used
If your integration exports a richer review-ready object, also confirm fields such as closure_state, responsibility_declared, threshold_status, trace_reference, authority_consistency_status, handoff_eligible, evidentiary_strength, degradation_reason, trace_continuity_status, trace_reconstruction_status, attribution_validity, and attribution_strength.
{
  "ok": true,
  "boundary_status": "live",
  "storage_status": "attached",
  "credential_gate": "trial_bearer_required",
  "authorized_project_id": "trial_proj_cec59281f5cfc093",
  "event_count": 1,
  "events": [
    {
      "project_id": "trial_proj_cec59281f5cfc093",
      "application_id": "tgtracing:assistant:customer_chat",
      "event_id": "evt_first_write_001",
      "session_id": "sess_first_write",
      "evidence_id": "evi_example_001",
      "closure_state": "behavior_complete",
      "responsibility_declared": false,
      "threshold_status": "not_met",
      "trace_reference": "tgtrace:sess_first_write:evt_first_write_001",
      "verification_url": "/?action=evidence-events&verify=1&evidence_id=evi_example_001"
    }
  ]
}
Evidence review surfaces

Separate exact evidence review from internal observation and triage

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.

Evidence Records
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. Typical query inputs include event_id, session_id, application_id, recorded_from, and recorded_to.
Observation window
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.
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.
Two-step workflow
Each recent evidence item shown in the observation window may link to the corresponding protected Evidence Records page. This creates a two-step workflow: observe live evidence activity first, then open exact records only when deeper inspection is needed.
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.
Metadata discipline

Use metadata as a stable extension field, not a raw dump

What belongs here
Put only additional stable context in metadata when it may be useful later and does not already belong in the required core fields.
Optional context admissibility
When available, use metadata.context_admissibility to carry a compact review-strengthening summary of input binding, runtime source, runtime scope, pollution flags, clean context hash, and recomposition posture. Keep it as a summary layer, not a raw slice dump.
What to avoid
Do not turn metadata into an uncontrolled export of raw internal state. That usually makes exported records harder to review instead of easier.
First-version rule
In the first rollout, keep metadata limited, intentional, and review-relevant so the record stays stable while the source system evolves.
Failure handling

Preserve the difference between behavior success and export success

Do not hide failure
If evidence export fails, the source system should not silently act as if the evidence was preserved. At minimum, record the export failure locally with enough context for investigation or retry.
Two separate truths
Whether the user-facing AI behavior happened and whether the evidence export succeeded are separate operational truths. They should not be conflated.
First rollout expectation
A minimum implementation does not need a complex retry system on day one, but it should avoid invisible evidence loss.
Privacy and minimization

Export what strengthens evidence, not everything available

User reference
Prefer stable user references over unnecessarily exposing direct identity when the same review value can be preserved with a safer identifier.
Summary-first design
Summaries are often better than raw payloads because they remain easier to review, more privacy-aware, and more stable across changing system internals.
Practical rule
A better evidence export path is not always a larger one. It is a clearer one.
Formal entry
The Evidence API start page is the main start point for a real integration. It leads into trial access, first-key delivery, first write, first read, and the initial working closure before deeper rollout work begins. Trial keys are project-bound, so the submitted project_id must match the project bound to the supplied key.
Boundary
You defined one stable user-facing behavior boundary that another reviewer can understand without extra explanation.
Quick split
Read the Protocol for contract, role, and boundary. Use the start page for access bootstrap and first closure. Use the Manual for implementation, verification, rollout, and live integration work, including project-bound trial key usage and mismatch troubleshooting.
Normalization and hash
You normalize timestamps, strings, booleans, and arrays consistently, then generate evidence_hash in the required protocol format.
Write and read
You can successfully POST records to CLARIXO and retrieve them back through filters that match real support and review workflows.
Human review value
Another human can look at one exported record and understand what happened, how it was delivered, and what the preserved outcome means.
Recommended rollout order

Start small, stabilize, then widen

Phase 1

Choose one surface first

Start with one application surface or one route family rather than widening across every product path at once.

Phase 2

Lock one event definition

Define what one evidence event means, then keep that meaning stable through the first rollout and verification cycle.

Phase 3

Normalize and verify

Build one payload-normalization layer, generate evidence_hash, export records, and validate retrieval before widening scope.

Phase 4

Expand deliberately

Only after the first surface is stable should the team expand to more routes, more applications, or more operator-assisted workflows.

Troubleshooting

Check the minimum failure signals first

When the first write does not close cleanly, do not guess. Check the authentication mode, project binding, and write result first. The fastest path is to identify which layer rejected the call before widening the investigation.

missing_bearer_token
The write request did not include an Authorization Bearer trial key. Confirm that the POST request sends Authorization: Bearer <trial_key> and that the write path is not dropping headers before submission.
invalid_or_inactive_trial_key
The supplied trial key is missing, expired, revoked, inactive, or no longer accepted for active trial use. Regenerate access through the Evidence API start flow or replace the key with a fresh active trial key before retrying the write.
project_id_mismatch
The submitted project_id does not match the project bound to the supplied trial key. Check both values directly. In mismatch handling, the server may surface the authorized project bound to the key, so do not assume the logged project_id is always the raw submitted event project.
First write success
A healthy first closure should show a successful POST result, a positive write count, and a retrievable exported record under the same project_id and application_id. After the first successful write, confirm that the returned record is readable enough for another human reviewer and that verify/read continuation is practical.
Cross-link

Need the contract document instead?

Use the Integration Protocol for the formal evidence export contract, role, boundary, minimum schema, and integrity rule. Use the Evidence API page for product overview and live handler examples. This manual is an implementation document for evidence export only and should not be treated as a runtime control, approval, or enforcement manual.
Open Integration Protocol Back to Evidence API