Contract Reference
Use this page as the exact field-level reference for the CLARIXO integration contract.
This reference defines the stable request, response, degraded, observability, structured error, and capability-proof surface for CLARIXO integrations. Use the Integration Manual for setup flow, the API page for capability-proof entry, and this page for exact contract-facing field meanings.
Request Identity
These fields define what surface the integration belongs to
A request is not production-ready just because it contains a message. It must also preserve the meaning of the host surface.
message
The user or operator message being sent into CLARIXO.
integration_source
The product or system source that owns the integration.
integration_mode
Normalized integration attribution mode. Hosts may omit it in the request. CLARIXO resolves
clarixo to first_party and a non-empty third-party integration.source to third_party.integration_module
The functional module inside the host product, such as assistant, workflow, or review surface.
integration_scene
The specific scene or surface meaning, such as customer_chat, internal_review, or support_triage.
integration_context
A structured context object carrying preserved page, identity, surface, session, or environment hints.
Response Core
These fields make the response structurally usable
Required
Healthy or degraded success
{
"ok": true,
"reply": "Example response text",
"actions": [],
"meta": {
"source": "clarixo",
"provider": "clarixo-native",
"intent": "customer_chat",
"mode": "direct",
"decision_state": "healthy"
}
}
Required
Structured failure
{
"ok": false,
"error": {
"type": "protocol_error",
"code": "missing_required_field",
"message": "Required response field 'reply' was not present.",
"retryable": false
}
}
Degraded And Observable
Degraded outcomes must stay explicit, and observable outcomes should stay machine-readable
Degraded
Minimum degraded semantics
A degraded success should still be valid JSON, still include reply text, and still expose a machine-readable degraded state.
Observability
Observable response hints
When available, observability data should preserve trace linkage, guard state, fallback usage, and integration identity without flattening them away.
{
"ok": true,
"reply": "The conversation can continue, but confidence is moderate.",
"actions": [],
"meta": {
"source": "clarixo",
"provider": "clarixo-native",
"intent": "customer_chat",
"mode": "guarded",
"decision_state": "watch",
"confidence": 0.73,
"integration_source": "example_app",
"integration_module": "assistant",
"integration_scene": "customer_chat",
"ops_final_status": "watch",
"ops_needs_review": 0,
"observability": {
"trace_id": "trace_01",
"guard_state": "watch",
"fallback_used": false
}
}
}
Capability And Access Truth
These fields explain what the current project or request is allowed to do
requested_capability
The capability currently being requested by the API path or runtime action, such as basic chat, AgentOps reading, approval reading, approval writing, or execution governance.
plan_code
The normalized project plan currently resolved for access control, such as trial, builder, pro, business, control, or enterprise.
billing_status
The current billing or activation state used together with the plan to determine whether a capability should be granted.
allowed_capabilities
The machine-readable capability allowlist resolved for the current plan and billing state.
authorized
The final authorization result for the requested capability after plan and billing checks are applied.
reason
The normalized reason for the authorization result, such as
ok, capability_not_allowed, billing_inactive, or capability_unknown.{
"requested_capability": "agentops.read",
"plan_code": "business",
"billing_status": "active",
"allowed_capabilities": [
"chat.basic",
"runtime.basic",
"agentops.read",
"agentops.queue"
],
"authorized": true,
"reason": "ok"
}
Usage Notes
How to use this page correctly
Use this page for
Exact field lookup, normalized response structure, stable contract semantics, and capability-proof field interpretation.
Do not use this page for
Implementation order, onboarding flow, troubleshooting sequence, or role ownership guidance.
Next page
Go back to the Integration Manual for setup flow and governance rollout, use the API page for capability-proof entry guidance, or continue to Compatibility Policy for stability and upgrade boundaries.