Guardrails

Dry-run evaluate a guardrail

Runs the full evaluation pipeline — the class expression, the guard, the context tool per context_mode, live runtime.* resolution — against caller-supplied args and guardrail_context, and returns the exact guardrail_evaluation record a real call would produce. Nothing executes, no approval item is filed, and no activity entry is written. This is the adoption path: preview a document's decisions against production-shaped calls before attaching it — or before editing a widely-attached one. Pass an optional tool_id to resolve runtime.tools.*.

post/v1/projects/{project_id}/guardrails/{guardrail_id}/evaluate

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/guardrails/{guardrail_id}/evaluate
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

guardrail_idstring required

Request body

argsobject

The proposed call's arguments (the args.* namespace).

guardrail_contextobject

The caller-supplied guardrail context (the context.* namespace), combined with the context tool per context_mode.

tool_idstring

Optional tool to resolve runtime.tools.* against.

Response

The would-be evaluation record (nothing executed)

kindstring

Always guardrail_evaluation.

guardrail_idstring
guardrail_versioninteger nullable

The governing version; null for a dangling reference (fail-closed C).

scope'project' | 'agent' | 'tool'
toolstring nullable
actionstring nullable
class'A' | 'B' | 'C' | 'D'

The resolved class (or the applied default_class).

decision'execute' | 'route_to_approval' | 'blocked' | 'tripwire'
guard_resultboolean nullable

The guard outcome; null when the call did not classify as B.

context_source'caller' | 'tool' | 'merged' | 'none'
context_snapshotobject

Flat map of only the vars the class/guard expressions referenced, keyed by fully-qualified path, frozen at evaluation-time values.

agent_idstring nullable
orchestration_run_idstring nullable
generation_idstring nullable

Example response

{
  "guardrail_id": "guard_V1StGXR8Z5jdHi6B"
}

Changes

No recorded changes to this operation across all 1 revision of this API.