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.