---
title: "Dry-run evaluate a guardrail"
method: POST
path: "/v1/projects/{project_id}/guardrails/{guardrail_id}/evaluate"
tags: ["Guardrails"]
---

# Dry-run evaluate a guardrail

`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`)

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.*`.

## Path parameters

- `guardrail_id` string, required

## Request body

- object
  - `args` object: The proposed call's arguments (the `args.*` namespace).
  - `guardrail_context` object: The caller-supplied guardrail context (the `context.*` namespace), combined with the context tool per `context_mode`.
  - `tool_id` string: Optional tool to resolve `runtime.tools.*` against.

## Response `200`

The would-be evaluation record (nothing executed)

- GuardrailEvaluation: The record produced by evaluating a guardrail against one call — written to the audit trail at dispatch time (one per applying guardrail) and returned verbatim by the dry-run endpoint.
  - `kind` string: Always `guardrail_evaluation`.
  - `guardrail_id` string
  - `guardrail_version` integer, nullable: The governing version; null for a dangling reference (fail-closed C).
  - `scope` 'project' | 'agent' | 'tool'
  - `tool` string, nullable
  - `action` string, nullable
  - `class` 'A' | 'B' | 'C' | 'D': The resolved class (or the applied default_class).
  - `decision` 'execute' | 'route_to_approval' | 'blocked' | 'tripwire'
  - `guard_result` boolean, nullable: The guard outcome; null when the call did not classify as B.
  - `context_source` 'caller' | 'tool' | 'merged' | 'none'
  - `context_snapshot` object: Flat map of only the vars the class/guard expressions referenced, keyed by fully-qualified path, frozen at evaluation-time values.
  - `agent_id` string, nullable
  - `orchestration_run_id` string, nullable
  - `generation_id` string, nullable

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)