Dry-run a Policy against a synthetic context

POST /v1/policies/{policy_id}/evaluate

Property	Value
Operation	`evaluate_policy`
Group	Policies
Scope	`policies:write`
Route class	`control`
Idempotency	`Idempotency-Key` accepted: a retry with the same key replays the first answer
Audit	Not audited: A dry run: it changes no state and reads no Call content, so it writes no Audit event (ADR 0012, orchestration-layer.md 3.12).
Released in	1.47.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Evaluates the draft, or a published version, at its hook against the synthetic context of the body, and answers the outcome, its resolution under the compliance tag, the action, the _rule row and, on request, the engine trace (FR-orchestration-8). Fields the body omits arrive as null; a root the hook does not carry is refused with validation_failed and policy_field_unavailable_at_hook. It writes nothing: no Call event, Audit event or Usage event.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the policies:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/policies/pol_.../evaluate" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {}
  }'

const response = await fetch(`${process.env.VOCAL_API}/v1/policies/pol_.../evaluate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "context": {}
  }),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/policies/pol_.../evaluate",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "context": {},
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`policy_id`	path	PolicyId	yes	The id of a Policy: `pol_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`idempotency-key`	header	string	no	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: PolicyEvaluateRequest.

Field	Type	Required	Description
`context`	PolicyContextInput	yes
`trace`	boolean	no	Return the engine's trace; false when omitted.
`version`	integer or `"draft"`	no	A published version, or `draft`, the default.

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	PolicyEvaluateResult
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`
`404`	`application/json`	ErrorEnvelope	`not_found`
`409`	`application/json`	ErrorEnvelope	`idempotency_in_progress`, `idempotency_key_reused`
`422`	`application/json`	ErrorEnvelope	`validation_failed`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is PolicyEvaluateResult.

Field	Type	Required	Description
`action`	PolicyAction or null	yes	The matched action with its parameters; null when not matched, and when it applies by failing closed.
`action_type`	PolicyActionType	yes
`applies`	boolean	yes	Whether the action applies after orchestration-layer.md 3.9: when matched, or when a compliance-tagged Policy fails closed.
`cause`	PolicyOutcomeCause or null	yes	Why the outcome is `error` or `timeout`; null otherwise.
`compliance_tag`	ComplianceTag or null	yes
`elapsed_us`	number	yes	The evaluation time in microseconds, as the engine measured it (a measurement of this run, never a budget).
`engine_version`	string	yes
`fail_closed`	boolean	yes	True when the action applies only because the compliance tag resolved an error or a timeout.
`hook`	HookPoint	yes
`object`	`"policy_evaluation"`	yes
`outcome`	PolicyOutcome	yes
`output`	any	yes	The engine's output as it returned it; null on an error.
`policy_id`	PolicyId	yes
`rule_id`	string or null	yes	The `_id` of the table row that matched (the `_rule` output), or null.
`trace`	array or null	yes	The engine trace when the request asked for it; null otherwise. Returned, never stored.
`version`	integer or `"draft"`	yes	The version that ran, or `draft`.