# CMCI API v1 — Quickstart
Integrate a **structural drift signal** into your AI agent, multi-agent workflow, or
response-generation pipeline in about two minutes. Send each output your system
produces; get back a structural-risk signal you can route on.
- **Base URL:** `https://api.coherix.ca`
- **Auth:** API key (Bearer token)
- **Integration:** one HTTP call per output
---
## 1. What CMCI API v1 does
CMCI API v1 monitors the **structure** of your AI system's outputs and tells you when an
output **deviates from that system's established structural baseline**, or **violates a
rule you define**. It is a signal layer for human-in-the-loop review and routing — not an
agent, and not a content judge.
It is useful for monitoring LLM agents, multi-agent systems, support bots, document- and
response-generation pipelines, and other automated workflows where you want an early,
lightweight signal that a system's output has changed shape or broken a constraint.
## 2. What it does not do
CMCI API v1 does **not**:
- judge whether an output is **true**, **factual**, or **hallucinated**;
- provide **semantic**, safety, or compliance guarantees;
- interpret the **meaning** of the prompt or the response;
- replace human review, moderation, or domain validation.
It reports **structural** signals only. Treat it as an early-warning layer, not a source of truth.
## 3. Authentication
All `/v1` routes require an API key, sent as a Bearer token:
```
Authorization: Bearer <CMCI_API_KEY>
```
Requests without a valid key are rejected. Keep your key server-side; never embed it in a
browser, mobile app, or public repository.
## 4. Send your first signal
Send an output your system produced. Use a **stable `system_id`** per monitored system.
```bash
curl -X POST "https://api.coherix.ca/v1/signals" \
-H "Authorization: Bearer <CMCI_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"system_id": "support-agent-prod",
"input": {
"response": "Your request was received. We will respond within one business day.",
"constraints": [
{ "type": "forbidden_terms", "value": ["guarantee", "refund"] },
{ "type": "max_sentences", "value": 5 }
],
"metadata": {
"agent": "support-v1",
"environment": "production"
}
}
}'
```
## 5. Calibrate a baseline
CMCI learns what "normal" looks like for each `system_id` from the outputs you send.
Send a series of **normal, representative outputs** for the same `system_id`. As these
accumulate, the system builds a **structural baseline**. While it is still learning,
`baseline_status` is `calibrating`; once enough observations exist, it becomes `ready`
and anomaly detection is active.
Guidance: send at least several representative outputs before relying on `anomaly_flag`.
Keep using the **same `system_id`** so the baseline reflects that specific system.
## 6. Check baseline state
```bash
curl "https://api.coherix.ca/v1/systems/support-agent-prod/state" \
-H "Authorization: Bearer <CMCI_API_KEY>"
```
Returns the current baseline status and how many observations back it:
```json
{
"system_id": "support-agent-prod",
"baseline_status": "ready",
"baseline_n": 24,
"signal_status": {
"constraint_risk": "reliable",
"anomaly_flag": "structural",
"drift_score": "indicative_pending_validation",
"stability_score": "indicative_pending_validation",
"regime": "heuristic",
"margin": "heuristic"
}
}
```
You can also inspect the recent drift trend:
```bash
curl "https://api.coherix.ca/v1/systems/support-agent-prod/drift" \
-H "Authorization: Bearer <CMCI_API_KEY>"
```
## 7. Send an anomalous signal
Once the baseline is `ready`, an output that is **structurally unlike** the baseline
(for example, a stack trace or a fragmented dump where the system normally returns short
prose) raises `anomaly_flag`, and a rule violation raises `constraint_risk`:
```bash
curl -X POST "https://api.coherix.ca/v1/signals" \
-H "Authorization: Bearer <CMCI_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"system_id": "support-agent-prod",
"input": {
"response": "ERROR 500\n- retry\n- fallback\n## STACK\n1\n2\n3\n{json:true} ;;; ??? ok. no."
}
}'
```
Example response:
```json
{
"system_id": "support-agent-prod",
"signal_id": "sig_9f2c1a7b8e4d0c31",
"timestamp": "2026-07-01T14:42:15Z",
"constraint_risk": "none",
"anomaly_flag": true,
"risk_level": "high",
"primary_issue": "structural_drift",
"recommendation": "human_review_recommended",
"drift_score": 0.95,
"stability_score": 0.19,
"regime": "ADAPTIVE",
"margin": -0.21,
"baseline_status": "ready",
"baseline_n": 25,
"constraint_violations": [],
"signal_status": {
"constraint_risk": "reliable",
"anomaly_flag": "structural",
"drift_score": "indicative_pending_validation",
"stability_score": "indicative_pending_validation",
"regime": "heuristic",
"margin": "heuristic"
}
}
```
## 8. Interpret the response fields
| Field | Meaning |
|---|---|
| `constraint_risk` | Reliable deterministic constraint check (`none` / `high`) |
| `anomaly_flag` | Structural deviation against the system baseline (`true` / `false`) |
| `risk_level` | Aggregate routing signal (`none` / `low` / `medium` / `high`) |
| `recommendation` | Suggested action: `none` / `monitor` / `human_review_recommended` |
| `baseline_status` | `calibrating` (still learning) / `ready` (anomaly detection active) |
| `baseline_n` | Number of baseline observations for this `system_id` |
| `constraint_violations` | List of the specific rules that were violated, if any |
| `drift_score`, `stability_score` | Indicative structural signals (see validation status below) |
| `regime`, `margin` | Heuristic engine outputs (indicative only) |
| `signal_status` | Tells you which fields are **reliable** vs **indicative** |
## 9. Claim boundaries / validation status
- **Reliable today:** `constraint_risk` (deterministic rules) and `anomaly_flag`
(structural deviation vs baseline). Build routing logic on these.
- **Indicative only:** `drift_score`, `stability_score`, `regime`, and `margin` are
provided as signals and are **`indicative_pending_validation`**. They remain indicative
until validated on held-out data (target AUC ≥ 0.70). Do not treat `drift_score` as a
validated metric or expose it as one.
- CMCI API v1 reports **structural** signals only. It does not detect truth,
hallucinations, semantic safety, or meaning.
## 10. Minimal Python example
```python
import requests
BASE_URL = "https://api.coherix.ca"
API_KEY = "<CMCI_API_KEY>"
def send_signal(system_id, response_text, constraints=None, metadata=None):
r = requests.post(
f"{BASE_URL}/v1/signals",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"system_id": system_id,
"input": {
"response": response_text,
"constraints": constraints or [],
"metadata": metadata or {},
},
},
timeout=10,
)
r.raise_for_status()
return r.json()
result = send_signal(
"support-agent-prod",
"Your request was received. We will respond within one business day.",
constraints=[{"type": "forbidden_terms", "value": ["guarantee", "refund"]}],
metadata={"agent": "support-v1", "environment": "production"},
)
if result["risk_level"] == "high":
# constraint_risk or anomaly_flag fired — send to a human
escalate_to_human_review(result)
```
## 11. Operational notes
- Use a **stable `system_id`** per monitored system, so the baseline reflects that system.
- **Do not send secrets** in `response` or `metadata` unless necessary for your use case.
- Use `metadata` for **non-sensitive** tags (agent name, environment, version).
- **Monitor `anomaly_flag` and `constraint_risk` first** — they are the reliable signals.
- Treat `drift_score` (and `stability_score`, `regime`, `margin`) as **indicative** until validated.
- Let the baseline reach `ready` before you rely on anomaly detection.
## 12. Positioning
CMCI API v1 gives your team an early, lightweight signal when an AI system's output drifts
from its normal structure or breaks a defined rule — so a human can review the cases that
matter, before they reach your users. It is a structural monitoring layer that complements,
and does not replace, your existing review and validation processes.