POST /api/v1/evaluate

Evaluate a proposed tool or agent action before dispatch. Returns ALLOW or DENY with an evidence record.

Call /api/v1/evaluate before your runtime dispatches the proposed action. Honor the returned decision before any side effect starts.

Use the endpoint and credentials issued for your environment. Public examples use the production host.

Request

POST /api/v1/evaluate HTTP/1.1
Host: sdkapi.sector8.ai
x-api-key: YOUR_API_KEY
x-client-id: YOUR_CLIENT_ID
Content-Type: application/json

{
  "tool_name": "bash",
  "arguments": {
    "command": "cat .env"
  },
  "caller_id": "engineer-42",
  "role": "developer",
  "session_id": "session-abc123",
  "owned_objects": ["repo-frontend"],
  "object_id": "repo-frontend",
  "operation": "read"
}

Request fields

Field	Required	Description
tool_name	yes	Tool or action being proposed
arguments	yes	Tool arguments as a JSON object
caller_id	no	Engineer or agent identifier recorded with the decision
role	no	Authorization role used in policy evaluation
session_id	no	Stable session identifier used for correlation and multi-turn analysis
owned_objects	no	Object IDs the caller owns, used for ownership checks
object_id	no	Target object for this call
operation	no	Requested operation used in policy evaluation
capability	no	Explicit capability override; defaults to tool_name when omitted

Response - ALLOW

{
  "decision": "ALLOW",
  "reason_code": "ALLOW_PASS",
  "evidence_hash": "4cb7f786d1f3b57e6f98f3e60d2eb6b81c402d6d3efeb6c9551049f7c14df2f0",
  "has_forensic_payload": false,
  "decision_trace_id": "17e797c0-eb5c-4f97-b4a1-2d3e4f5a6b7c",
  "policy_version_id": "0dbca364d66447469637bafa2282e635124fcb99eecd6383038e3b652577ebc7"
}

Your runtime may dispatch the proposed action.

Response - DENY

{
  "decision": "DENY",
  "reason_code": "SENSITIVE_PATH_BLOCKED",
  "evidence_hash": "bdbde1558fb883573b0f6e8630ccba1edaf6bed8cb035fa6a48912809149f287",
  "has_forensic_payload": true,
  "decision_trace_id": "32819155-d21a-49c8-9509-79338d980fa9",
  "policy_version_id": "5d61927dcac73a97e9e3c7ee0dbca364d66447469637bafa2282e635124fcb99"
}

Your runtime must not execute the proposed action.

Branch on decision. The same proposed action may return different reason_code values depending on which policy layer blocks it (for example PRE_FILTER_BLOCK vs a more specific path or injection code).

Human hold

POST /api/v1/evaluate is strictly synchronous and returns ALLOW or DENY. If a proposed action would require waiting for a human on this path, evaluate fails closed and returns DENY with REVIEW_REQUIRED_FAIL_CLOSED.

A human hold is available on the MCP connector path. The connector pauses until a reviewer approves or denies, then returns ALLOW or DENY. Unresolved holds fail closed.

reason_code and policy_version_id are opaque support/evidence identifiers. Values depend on your active policy, environment, and evaluation path. Do not build exhaustive dispatch logic on them. The contract is that the runtime receives a decision before the proposed action executes.

Response fields

Field	Type	Description
decision	string	"ALLOW" or "DENY"
reason_code	string|null	Opaque machine-readable reason for support/display. Illustrative values: reason codes. Branch on decision, not on a specific code.
evidence_hash	string	Fingerprint of the decision evidence for correlation and integrity checks
has_forensic_payload	boolean	Indicates whether additional forensic detail is attached to the record
decision_trace_id	string	Unique audit identifier for this evaluated action
policy_version_id	string|null	Non-empty policy identifier applied to the decision. May be a binding hash or a runtime version label depending on evaluation path; do not assume one format across all verdicts.

Runtime semantics

Honor the decision before dispatch:

decision	Runtime behavior
ALLOW	May execute the proposed action
DENY	Must block the proposed action
Missing / unknown	Fail closed; do not execute

Fail closed if the evaluate call fails, times out, or returns an unknown decision. Do not execute the proposed action by default.

Client timeout

Set an evaluate HTTP client timeout of at least 10 seconds. 10s is the recommended default.

Observed evaluate latency on the public production host is commonly about 1–4 seconds. Slower environments and cold paths can take longer. If you set a 1–2s timeout, fail-closed will block legitimate ALLOW traffic.

Telemetry

Every evaluate call is recorded with the returned decision artifact. Denied actions can feed alert and incident workflows when those integrations are configured for your tenant.

See Guardrails for broader telemetry context and the Quickstart for the first evaluate-before-dispatch proof.