Explain API

Turn a policy decision into a plain-language explanation with POST /v1/explain, and retrieve it later with GET /v1/explain/{violation_id}.

Explanations are deterministic: the enforcer builds them from templates and the decision fields, with no model in the loop, so the same input always gives the same text. Use them to tell a user why an action was refused and what to do next. Both endpoints use your unified tenant API base URL and a runtime key; see Authentication.

Create an explanation

POST/v1/explain

Builds an explanation from the decision fields you send, stores it under the tenant_id and violation_id, and returns it. It does not look the decision up, so pass the values from the EnforcementDecision you received.

Body parameters

All fields are optional. Unset values fall back to neutral defaults.

tenant_idstring

Your Thoth tenant identifier.

violation_idstring

The violation_id from a BLOCK decision. Used to store and retrieve the explanation.

session_idstring

Session the decision belongs to.

agent_idstring

Agent that attempted the action.

user_idstring

User who initiated the action.

tool_namestring

Tool the agent tried to call.

decision"ALLOW" | "STEP_UP" | "MODIFY" | "DEFER" | "BLOCK"

The decision to explain. Defaults to BLOCK.

decision_reason_codestring

Reason code from the decision.

action_classificationstring

Action class, which selects the wording.

risk_scorenumber

Risk score from the decision.

severitystring

Severity to report.

regulatory_regimesstring[]

Regimes to name in the regulatory context.

matched_rule_idsstring[]

Rules that matched.

matched_control_idsstring[]

Controls that matched.

policy_referencesstring[]

Policy references to cite.

approved_scopestring[]

The scope supplied with the original call.

step_up_timeout_secondsinteger

Hold timeout, for step-up explanations.

occurred_atstring (ISO 8601)

When the action happened. Defaults to now.

Returns

what_happenedstring

What the agent tried to do, and when.

why_it_was_blockedstring

Why policy stopped it.

what_to_do_nextstring

What the user can do, including how to request an exception.

business_impactstring

The risk the policy guards against.

request_urlstring

Link to request a policy exception, when the dashboard is configured.

severitystring

Reported severity.

regulatory_contextstring | null

Regulatory framing, when regimes apply.

The response also echoes the identifiers and decision fields you sent (violation_id, tenant_id, session_id, agent_id, user_id, tool_name, decision, decision_reason_code, action_classification, risk_score, regulatory_regimes, matched_rule_ids, matched_control_ids, policy_references) and a timestamp.

Request

curl -X POST "$THOTH_API_URL/v1/explain" \
  -H "X-API-Key: $THOTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "acme-corp",
    "violation_id": "550e8400-e29b-41d4-a716-446655440000",
    "session_id": "550e8400-e29b-41d4-a716-446655440001",
    "agent_id": "invoice-processor-v2",
    "user_id": "user-123",
    "tool_name": "submit_payment",
    "decision": "BLOCK",
    "decision_reason_code": "scope_violation",
    "risk_score": 0.91,
    "approved_scope": ["search_docs", "read_invoice"],
    "occurred_at": "2026-03-13T10:00:00Z"
  }'

200 OK

{
  "violation_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "acme-corp",
  "session_id": "550e8400-e29b-41d4-a716-446655440001",
  "agent_id": "invoice-processor-v2",
  "user_id": "user-123",
  "tool_name": "submit_payment",
  "what_happened": "Your agent `invoice-processor-v2` attempted to execute a command using `submit_payment` at 2026-03-13 10:00:00 UTC.",
  "why_it_was_blocked": "This execute action violated a configured policy guardrail.",
  "what_to_do_next": "If this action is required for your workflow, submit a policy exception request. Reference `550e8400-e29b-41d4-a716-446655440000`. Target response time is 24 hours.",
  "business_impact": "This action could execute privileged behavior outside approved automation boundaries.",
  "request_url": "https://app.atensecurity.com/thoth/admin/policy-exceptions?violation_id=550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-03-13T10:00:01Z",
  "severity": "medium",
  "regulatory_context": null,
  "decision": "BLOCK",
  "decision_reason_code": "scope_violation",
  "action_classification": null,
  "risk_score": 0.91,
  "regulatory_regimes": [],
  "matched_rule_ids": [],
  "matched_control_ids": [],
  "policy_references": []
}

Generated by the enforcer's explainer from the request above. Wording varies with action_classification, decision and your organization's settings.

curl "$THOTH_API_URL/v1/explain/550e8400-e29b-41d4-a716-446655440000?tenant_id=acme-corp" \
  -H "X-API-Key: $THOTH_API_KEY"

404 Not Found

{
  "detail": "human explanation not found"
}

Explain API

Create an explanation

Body parameters

Returns

Retrieve an explanation

Path parameters

Query parameters

Returns