# Guardrails API The two admin-plane guardrail endpoints — the evidence read surface and the simulate dry run — with real payloads. Source: https://tokentriage.com/docs/reference/guardrail-api --- import Callout from '../../../components/Callout.astro'; import NextSteps from '../../../components/NextSteps.astro'; Two endpoints run on the **admin** plane under `/tt/api/v1`, with the `viewer` role. Stored-content subjects additionally require explicit privileged content authorization. The generated typed contract is rendered at [/api](/api). | Method & path | Purpose | |---|---| | `GET /tt/api/v1/guardrails/evidence` | Retained execution coverage, findings and adjudication over the served window | | `POST /tt/api/v1/guardrails/simulate` | Named embedded detector diagnostics or policy dry run; never live enforcement | ## `GET /guardrails/evidence` ```console $ curl -s http://127.0.0.1:9090/tt/api/v1/guardrails/evidence | jq '{coverage, suspension_rows, uninspected_rows, suspensions, adjudication, provenance}' ``` - **`coverage`** counts rows with receipts, complete and incomplete inspection, not-selected rows, legacy-unknown rows and actual external attempts. An old row without a versioned receipt stays unknown; no finding is not evidence of inspection. - **`lineages[]`** groups observed findings by detector/version, with binding, phase, effect and confidence censuses. An empty lineage list says no findings were retained. - **`configured[]`** is the live policy roster. `fired: false` means no observed fire in the window, not that a detector was healthy or completed. Compare it with execution coverage. - **`suspensions[]`** is the per-reason census. `suspension_rows` counts affected rows; optional `uninspected_rows` remains absent when historical coverage cannot be established. - **`adjudication`** carries observed true-positive and false-positive counts, denominators and optional detector/version splits. `quality_sources` is a separate quality-source report, not a replacement for those correctness counts. Traffic or fire volume supplies no ground truth. - **`provenance`** describes the source, window and truncation. `guarded_rows` and `engaged_rows` are descriptive denominators, not proof of complete protection. Guardrail evidence remains separate from routing promotion evidence. Guardrail findings cannot license routing promotion. Confidence intervals require a licensed calibration artifact; malformed envelopes are refused and counted rather than synthesized or averaged. ## `POST /guardrails/simulate` Name exactly one subject: `content`, `req_id` or `dataset`. A `profile` selects a current named profile; absence uses the deployment default. `phase` defaults to `input` and also accepts `output`. The `key` selector is recognized but **per-key simulation is not implemented and is refused**. Reading a stored request supplies content, not its historical key overrides. ```console $ curl -s -X POST http://127.0.0.1:9090/tt/api/v1/guardrails/simulate \ -H 'Content-Type: application/json' \ -d '{"operation_kind":"detector_diagnostics","content":"mail ada@example.com","phase":"input"}' ``` | `operation_kind` | Meaning | |---|---| | `detector_diagnostics` | Default for literal text; probes detectors on that text | | `policy_dry_run` | Default for stored subjects; uses the serving extractor and sequential policy planner against the current selected profile | Every report carries `mode: simulate` and `enforced: false`. It includes `operation_kind`, `generation`, the selected profile/policy reference, case inspection states and execution records. Read `coverage` for total, selected, missing, unreadable, cap-excluded and truncated-body counts. `max_cases` cannot exceed the server cap of 200; excluded and unavailable cases stay disclosed. `cases[].fires[]` reports candidate actions and admission decisions. An action label or `action_implemented` is not evidence of production transformation or delivery. Findings expose bounded safe metadata and spans, not submitted text or detector detail strings. Only embedded detectors run; external detectors are explicitly skipped. Policy dry runs do not exercise external calls, stream framing, provider retries, re-identification or client delivery. Latency measures the selected operation on the available host; it is neither a production latency floor nor a concurrent-load prediction. Read `notes[]` for its scope. Hot reload publishes the simulator with the runtime snapshot. A new operation uses the current generation; an in-flight operation retains its captured generation. Compare report generation and policy reference when checking reload behavior. ## Access and unavailable results Stored-content simulation requires the privileged `content:read` management permission and a successful audit append before reading stored content. An ordinary wildcard read grant is insufficient. This is a global management content scope: no per-record ownership or tenant isolation check is provided by this endpoint. The API does not read a local corpus directory; `--corpus` is a CLI-only subject. An unwired feature returns `404 feature_absent`. Evidence source failures and active-operation deadlines/cancellation return `503 evidence_unavailable`; exhausted query capacity returns `429 rate_limited`. A missing stored request returns `404 not_found`; a dataset with no readable bodies returns `404 feature_absent`. In a successful nonempty dataset report, missing or unreadable selected bodies remain explicit coverage gaps. Invalid requests and unsupported selectors return validation errors, including `422 validation_failed` for rejected simulation policy. No partial report is returned as complete after active cancellation.