Enforcement API

Check a proposed tool call against policy with POST /v1/enforce, and poll a step-up hold with GET /v1/enforce/hold/{hold_token}.

The SDKs call these endpoints for you before every tool execution. Call them directly only when you are building a custom integration. Both use your unified tenant API base URL and a runtime key with execute permission; see Authentication.

Check a tool call

POST/v1/enforce

Evaluates a proposed tool call against your configured server policy, the authenticated identity and the request context, and returns a decision before the tool runs.

approved_scope is a list you supply, not an authorization grant, and the requested enforcement_mode informs evaluation without guaranteeing an outcome. Always act on the returned decision; never run the raw callback after a refusal or an unresolved hold.

Body parameters

agent_idstringrequired

Agent identifier.

tenant_idstringrequired

Your Thoth tenant identifier.

tool_namestringrequired

Name of the tool the agent wants to call.

session_idstringrequired

Current session identifier.

user_idstringrequired

User who initiated the agent action.

approved_scopestring[]required

Tool names the agent is intended to use in this session.

session_tool_callsstring[]required

Tool names already called in this session, in order.

enforcement_modestringrequired

One of observe, progressive, step_up or block.

tool_argsobject

Proposed tool arguments, used for policy and redaction checks.

environmentstring

Policy environment tag. Defaults to prod.

session_intentstring

Declared workflow intent for minimum-necessary checks.

purposestring

Declared purpose for purpose-aware filtering.

data_classificationstring

Declared data class used by policy controls.

endpoint_idstring

Endpoint or workstation identifier for attribution.

fleet_idstring

Fleet identifier for scoped governance.

enforcement_trace_idstring

Correlation ID carried through decision evidence.

identity_bindingobject

Identity tuple for identity and freshness enforcement.

auth_contextobject

Canonical auth context for attribution.

delegation_contextobject

Delegation-chain context for confused-deputy protection.

model_namestring

Model identifier for model-governance checks.

model_providerstring

Model provider for allowlist checks.

token_countnumber

Planned token usage for cost and threshold controls.

estimated_cost_usdnumber

Planned spend for budget controls.

metadataobject

Additional context propagated to decision evidence.

Returns

An EnforcementDecision. Act on decision:

ALLOW: run the tool. If authorization_decision is MODIFY, run it with modified_tool_args instead of the original arguments (for example, after outbound redaction).
STEP_UP: do not run the tool yet. Poll the hold_token until the hold resolves. A policy deferral (authorization_decision: "DEFER") is returned this way.
BLOCK: do not run the tool. Surface reason and keep violation_id for audit.

decision"ALLOW" | "STEP_UP" | "BLOCK"required

The verdict to act on.

authorization_decision"ALLOW" | "DENY" | "MODIFY" | "STEP_UP" | "DEFER"

Normalized authorization outcome recorded in decision evidence.

reasonstring

Human-readable explanation.

decision_reason_codestring

Stable machine-readable reason code.

modified_tool_argsobject

Arguments to use instead of the originals. Present with MODIFY.

modification_reasonstring

Why the arguments were changed. Present with MODIFY.

hold_tokenstring

Token to poll. Present with STEP_UP.

step_up_timeout_secondsinteger

How long the hold stays open. Present with STEP_UP.

violation_idstring

Audit ID for the refusal. Present with BLOCK.

risk_scorenumber

Risk score used in the decision.

latency_msnumber

Enforcer evaluation time in milliseconds.

Evidence and explainability fields may also be present, including enforcement_trace_id, receipt, decision_evidence, score_components, top_contributors, matched_rule_ids, matched_control_ids, policy_references, model_signals and policy-pack version metadata.

Request

curl -X POST "$THOTH_API_URL/v1/enforce" \
  -H "X-API-Key: $THOTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "invoice-processor-v2",
    "tenant_id": "acme-corp",
    "tool_name": "submit_payment",
    "session_id": "550e8400-e29b-41d4-a716-446655440001",
    "user_id": "user-123",
    "approved_scope": ["search_docs", "read_invoice"],
    "session_tool_calls": ["search_docs"],
    "enforcement_mode": "progressive"
  }'

Responses

200 OK

{
  "decision": "ALLOW",
  "decision_envelope_version": "1.0",
  "authorization_decision": "ALLOW",
  "reason": "tool is within approved scope",
  "decision_reason_code": "policy_allow",
  "risk_score": 0.12,
  "latency_ms": 18.4
}

Values are illustrative. Use tool names covered by your configured policy.

Poll a step-up hold

GET/v1/enforce/hold/{hold_token}

Returns the state of a pending step-up hold. Poll until resolved is true or your own timeout passes, then act on resolution. Treat anything other than ALLOW as a refusal. The SDKs run this loop for you.

Path parameters

hold_tokenstringrequired

The hold_token from a STEP_UP decision.

Returns

tokenstring

Hold token identifier.

tenant_idstring

Tenant associated with the hold.

agent_idstring

Agent that requested the call.

tool_namestring

Tool held for approval.

session_idstring

Session correlation ID.

expires_atstring (ISO 8601)

When the hold expires.

resolvedboolean

false while pending, true once resolved.

resolution"ALLOW" | "BLOCK" | null

Final decision once resolved.

resolved_bystring | null

Approver identity, or timeout.

resolved_atstring | null

When the hold was resolved.

reasonstring | null

Resolution reason, when available.

step_up_timeout_secondsinteger | null

How long the hold stays open.

initial_receiptobject

Decision receipt for the original STEP_UP decision.

terminal_receiptobject

Decision receipt for the final outcome, once resolved. The Python SDK attaches it to decision evidence.

The response contains only these fields. An unknown hold token returns 404; a hold that belongs to a different caller returns 403.

Request

curl "$THOTH_API_URL/v1/enforce/hold/sfn-abc123" \
  -H "X-API-Key: $THOTH_API_KEY"

Responses

200 OK

{
  "token": "sfn-abc123",
  "tenant_id": "acme-corp",
  "agent_id": "invoice-processor-v2",
  "tool_name": "submit_payment",
  "session_id": "550e8400-e29b-41d4-a716-446655440001",
  "expires_at": "2026-03-13T10:15:00.000Z",
  "resolved": false,
  "resolution": null
}

poll_hold.py

import os
import time
 
import httpx
 
 
def wait_for_hold(hold_token: str, timeout_seconds: int = 900) -> str:
    base = os.environ["THOTH_API_URL"].rstrip("/")
    headers = {"X-API-Key": os.environ["THOTH_API_KEY"]}
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        resp = httpx.get(f"{base}/v1/enforce/hold/{hold_token}", headers=headers, timeout=10)
        resp.raise_for_status()
        hold = resp.json()
        if hold.get("resolved") is True:
            return hold.get("resolution") or "BLOCK"
        time.sleep(5)
    return "BLOCK"  # treat an unresolved hold as a refusal