Skip to content
Brutor AI Docs

Assurance API

All under the Control Plane (:5050), admin-authenticated.

Endpoint Purpose
GET /v1/admin/ai-systems Fleet board with governance gaps
GET /v1/admin/ai-systems/{id}/runs Run ledger
GET /v1/admin/ai-systems/{id}/runs/stats Cost, trajectory length, tool errors and outcome mix for a window — plus the coverage split (observed_pct, chain_integrity_pct, asserted_pct, external_pct) and client-reported outcomes with their own coverage
GET /v1/admin/ai-systems/{id}/runs/timeseries The same signals bucketed for charts — hourly at 48h and under, daily above
GET /v1/admin/ai-systems/{id}/liveness Expectation + current status
GET /v1/admin/ai-systems/{id}/baselines What normal looks like
GET /v1/admin/ai-systems/{id}/drift Findings for one system
GET /v1/admin/drift Tenant-wide drift feed
POST /v1/admin/drift/{id}/ack Acknowledge — stays open
POST /v1/admin/drift/{id}/{resolve,false-positive} Close with a kind and a note (kind required); returns the epoch or incident window it wrote and the seal
GET /v1/admin/ai-systems/{id}/baseline-epochs Baseline epochs of a system
GET/POST /v1/admin/ai-systems/{id}/incident-windows Incident windows that apply to a system (its own and tenant-wide) / declare one for it
GET/POST /v1/admin/incident-windows · PATCH/DELETE /v1/admin/incident-windows/{id} Tenant-wide listing and declaration (omit ai_system_id for every system); edit; withdraw — each change sealed
GET /v1/admin/ai-systems/{id}/contracts Version history + conformance
POST /v1/admin/ai-systems/{id}/contracts Mint from live config
GET /v1/admin/ai-systems/{id}/contracts/current The contract governing runs right now
GET /v1/admin/ai-systems/{id}/contracts/{version} One version with the closure it stamped — the list omits it
GET /v1/admin/ai-systems/{id}/contracts/{version}/diff Widened vs narrowed
POST /v1/admin/contracts/{id}/{approve,reject,promote} Contract workflow
GET /v1/admin/ai-systems/{id}/lifecycle Transition requirements
POST /v1/admin/ai-systems/{id}/lifecycle Attempt a transition
GET/PUT /v1/admin/ai-systems/{id}/envelope The operating envelope declaration
GET /v1/admin/ai-systems/{id}/contracts/{ver}/export Canonical AI System Contract document
GET /v1/admin/ai-systems/{id}/assurance/history/{rid}/export A snapshot as a signed Assurance Certificate
GET /v1/admin/standards · GET /v1/admin/standards/{slug}/schema The published JSON Schemas both documents validate against
GET /v1/admin/ai-systems/{id}/evidence External evidence artifacts
POST /v1/admin/ai-systems/{id}/evidence Attach one (kind, uri, sha256, assessor, validity)
PATCH /v1/admin/ai-systems/{id}/evidence/{eid} Update an artifact’s metadata
DELETE /v1/admin/ai-systems/{id}/evidence/{eid} Detach (captured report snapshots keep it)
GET /v1/admin/ai-systems/{id}/response-policies Policies applying here, inherited included
POST /v1/admin/ai-systems/{id}/response-policies Arm a policy
POST /v1/admin/ai-systems/{id}/response-policies/preview Blast radius + what it would do
GET /v1/admin/ai-systems/{id}/responses What fired, and what was refused
POST /v1/admin/ai-systems/{id}/restore Undo an automatic tightening
GET /v1/admin/ai-systems/{id}/replay Suite state and what the gate makes of it
POST /v1/admin/ai-systems/{id}/replay/suite Freeze a stratified suite from recent traffic
POST /v1/admin/ai-systems/{id}/replay/run Request a replay run
GET /v1/admin/ai-systems/{id}/health Worst-of score with its components
GET /v1/admin/ai-systems/{id}/assurance The live Assurance Report
POST /v1/admin/ai-systems/{id}/assurance Capture an immutable snapshot
GET /v1/admin/ai-systems/{id}/assurance/history Captured snapshots

Detection itself — run finalization, liveness and drift sweeps — runs in the Core Proxy alongside the request path, not in the Control Plane.

Two ledger-adjacent admin routes live outside the AI-Systems tree:

Endpoint Purpose
PUT /v1/admin/tenants/{id} with data_retention The tenant’s retention policy — store_bodies, body_days, log_days, run_days
POST /v1/admin/data-erasure · GET /v1/admin/data-erasure Erase a data subject from the ledger; list erasure events

Run finalization and the OTel inlet (Core Proxy)

Section titled “Run finalization and the OTel inlet (Core Proxy)”

Two more writes belong to the runtime plane, because they come from the systems themselves rather than from admins:

Endpoint Purpose
POST /v1/runs/{root_task_id}/end Close a run explicitly with {"state": "completed", "outcome": "resolved"} — state is the terminal state, outcome the client-reported outcome; both optional. The header forms are X-Brutor-Run-End and X-Brutor-Run-Outcome on the last call
GET /v1/runs/{root_task_id} Inspect one run as the ledger sees it
POST /v1/ingest/otel/v1/traces The OpenTelemetry GenAI inlet — OTLP/HTTP JSON only; API-key authenticated

Outcome feedback (Core Proxy)

Section titled “Outcome feedback (Core Proxy)”

One assurance write does not live on the Control Plane. Ratings come from end users, not admins, so they are collected by the portal API on the Core Proxy (:8100) under the end user’s own portal session:

Endpoint Purpose
POST /v1/portal/runs/{run_id}/feedback Rate the run that produced an answer
Request
{ "score": 1, "comment": "optional" }
Response 200
{ "run_id": "01JBRUTORRUNROOT0000000000", "score": 1 }

score is 1 (up), -1 (down) or 0 (withdraw a rating — the response then carries "score": null). run_id is the value the gateway returned in the x-brutor-run-id response header.

Ratings are stored per user per run, so re-rating replaces that user’s own rating and leaves everyone else’s alone. A run the caller did not take part in returns 404 — “this run exists but is not yours” is itself a fact about someone else’s traffic.

Section titled “Related”