Runtime API

POST/v1/evaluate/agent-plan

Evaluate a proposed agent plan for excessive agency (LLM03)

Evaluate a proposed multi-step agent plan for excessive agency (LLM03).

Bearer token or X-API-Keyscope: org memberSubject to per-plan eval quotaoperation_id: runtime.evaluateAgentPlan

Authentication

Send either Authorization: Bearer <token> or X-API-Key: <token>. Runtime token — create via POST /v1/orgs/{org_id}/tokens/runtime. Scoped to one project and environment. Requests without a valid credential are rejected with 401.

Where this runs

This endpoint is served by the ZNYX runtime you host, so the base URL is your own runtime host, not api.znyx.ai. Prompts, responses, retrieved context, and tool payloads are evaluated inside your boundary, and there is no supported production endpoint on our side that evaluates your application’s traffic. Text you paste into the console’s playground is the one exception, and it is not persisted.

SDK install

pip install znyx-sdknpm install @znyx/sdk

Code samples

Request

curl -X POST "$ZNYX_RUNTIME_URL/v1/evaluate/agent-plan" \
  -H "Authorization: Bearer $ZNYX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "string",
  "tenant_id": "string",
  "app_id": "string",
  "agent_id": "default",
  "env": "prod",
  "metadata": null,
  "trace_id": null,
  "session_id": null,
  "span_id": null,
  "plan": null
}'

Response

application/json

Successful Response

{
  "request_id": "string",
  "decision": "ALLOW",
  "risk_score": 0,
  "policy_version": "string",
  "rule_hits": [
    {
      "rule_id": "string",
      "severity": "low",
      "message": "string"
    }
  ],
  "sanitized_text": null,
  "sanitized_tool_args": null,
  "user_message": null,
  "developer_message": null,
  "latency_ms": null,
  "trace_id": null,
  "session_id": null,
  "span_id": null,
  "detector_results": [
    {
      "detector_name": "string",
      "decision": null,
      "risk_score": 0,
      "latency_ms": 0,
      "rule_hits": [
        {
          "rule_id": "string",
          "severity": "low",
          "message": "string"
        }
      ],
      "transformed": false,
      "confidence": null,
      "calibrated_score": null,
      "label_scores": null,
      "model_version": null,
      "execution_mode": null,
      "fallback_path": null,
      "external_egress": false,
      "threshold": null,
      "layer_results": [
        {
          "execution_mode": "string",
          "decision": null,
          "native_score": null,
          "normalized_score": null,
          "confidence": null,
          "calibrated_score": null,
          "label_scores": null,
          "category": null,
          "threshold": null,
          "model_id": null,
          "model_version": null,
          "rubric_version": null,
          "latency_ms": null,
          "token_count": null,
          "cost_usd": null,
          "rationale": null,
          "evidence_spans": null,
          "external_egress": false,
          "fallback_reason": null,
          "selected": false
        }
      ]
    }
  ],
  "quality": null,
  "field_errors": [
    {
      "path": "string",
      "message": "string",
      "expected": null,
      "actual": null
    }
  ],
  "remediation": null,
  "pending_review_id": null
}

Schema: object

Header parameters

Name	Type	Required	Description
X-API-Key#header	string \| null	optional	-
authorization#header	string \| null	optional	-

Request bodyrequired

Field	Type	Required	Description
request_id	string	required	-
tenant_id	string	required	-
app_id	string	required	-
agent_id	string	optional	-
env	string	optional	-
metadata	object \| null	optional	-
trace_id	string \| null	optional	-
session_id	string \| null	optional	-
span_id	string \| null	optional	-
plan	any	required	The proposed plan (list of steps / structured JSON)

Responses

Status	Description
200	Successful Response
422	Validation Error

Response schema

request_idrequiredstring

decisionrequiredDecision

risk_scorerequiredinteger

Risk score from 0-100

policy_versionrequiredstring

rule_hits

sanitized_textstring | null

Sanitized text if REDACT/TRANSFORM

sanitized_tool_argsobject | null

Sanitized tool args (for tool evaluation)

user_messagestring | null

Safe message to show end-user when blocked

developer_messagestring | null

Developer-facing explanation

latency_msinteger | null

Total evaluation latency in milliseconds

trace_idstring | null

Trace ID for distributed tracing correlation

session_idstring | null

Session/conversation ID echoed from request

span_idstring | null

Span ID within a trace echoed from request

detector_results

Per-detector timing breakdown

qualityQualityReport | null

Response quality scores (output context only)

field_errors

Field-level errors from structured output validation

remediationRemediationResult | null

Remediation action applied after detector decision

pending_review_idstring | null

Human review queue ID if ask_human remediation was triggered

Errors & what triggers them

Code	Trigger	Fix
401	Missing or expired Authorization header.	-
403	Token does not have the required role (admin / editor).	-
404	Target resource does not exist in this org.	-
422	Request body failed validation.	-