Interventions API
Report a configuration change from your control system, and read whether the same cohort recovered. All routes need an admin credential. See Recovery after a change for what the check means and what it does not say.
POST /v1/interventions
Send up to 100 changes in one request.
POST /v1/interventions
authorization: Bearer <admin credential>
content-type: application/json
{ "changes": [ <change>, ... ] }
A change has these fields:
| Field | Required | Meaning |
|---|---|---|
external_id |
yes | The control system's own id for this change: letters, digits and _ . : / -, up to 200 characters. With source it is the idempotency key. |
source |
yes | The control system reporting it, for example launchdarkly. |
agent_id |
yes | The agent the change applies to. It must be registered. |
flag |
yes | The flag that changed. It is matched against the feature_flag.key the agent's spans carry (see Configuration). |
to_variant |
yes | The variant now served. |
from_variant |
no | The variant before. |
kind |
no | rollback, rollout or change (the default). |
changed_at |
yes | When the control system made the change. Not more than five minutes in the future. |
serving_since |
no | When the affected configuration began serving, which is when the regression began. Not after changed_at. Without it the seven days before the change are treated as the regression, and the fourteen days before that as the reference. |
cohort |
no | { "tag", "value" }: a cost tag name and value. Both are required if it is sent. Without it the change is for every run of the agent. |
actor |
no | Who or what made the change: an id or a service name. An email address is refused. |
evidence_ref |
no | A pointer into the control system, up to 500 characters. Never content. |
evidence_sha256 |
no | A 64 character hex digest of what the pointer refers to. |
reason |
no | Up to 500 characters. |
Any other field is refused, so a prompt, an answer or personal data cannot be sent by accident.
Response. 201 when at least one change was recorded or recognised as a repeat, 400 when none was or the request is not a list, 413 over 100. The body lists each item as recorded (with an intervention_id), duplicate or rejected (with the reason). One bad item never stops the others. The same external_id from the same source with different content is rejected, so a retry can never rewrite what you sent.
GET /v1/interventions
GET /v1/interventions?agent_id=<id>&limit=<n> lists the changes, newest first (up to 500).
GET /v1/interventions/:id/recovery
Reads the runs and the evaluator's results and returns a provantix.recovery.v1 document:
{ "schema": "provantix.recovery.v1",
"verdict": "recovered" | "not_recovered" | "insufficient_evidence" | "not_comparable",
"reason": "...", "statement": "...", "cohort": "plan=gold",
"windows": { "reference": {from,to}, "regression": {from,to}, "post": {from,to} },
"runs": { "reference": 40, "regression": 40, "post": 40, "truncated": false },
"checks": { "served": {...}, "steps": {...}, "quality": {...}, "regression": {...}, "held": {...} },
"thresholds": { ... }, "source": "..." }
Each check has a status (pass, fail, insufficient_evidence, unknown, not_declared or incomparable), a reason and the numbers with their denominators. Only runs that have ended (nothing recorded in the last 30 minutes) are counted. The result is computed on read from the stored records; it is not stored.
What is not here
Provantix does not execute, schedule or approve a change, and it does not read your control system's audit log. You send the change; Provantix records it and checks what followed.