Evaluate API

Send content for policy evaluation via the Aguardic REST API.

Overview

The Evaluate endpoint is the primary way to check content, actions, or AI outputs against your governance policies. Send a request with the content to evaluate, and Aguardic returns an outcome (ALLOW, DENY, or FLAG) along with any policy violations.

Using TypeScript? The official SDK handles authentication, response unwrapping, and type safety automatically. See the JavaScript / TypeScript SDK for a simpler integration path.

Policies are determined automatically from the integration's bindings -- you do not specify which policies to evaluate against. Only policies actively bound to the integration (identified by your API key) are checked.

Endpoint

POST /v1/evaluate

Authentication

Include your per-integration API key in the Authorization header. See Authentication for details.

Request Body

Field	Type	Description
`input`required	`object`	The content or action to evaluate. Pass whatever structure your integration uses -- there is no fixed schema.
`targetKey`	`string`	Identifies the evaluation target (e.g., `"chat"`, `"email-send"`, `"file-upload"`). Max 1000 characters.
`targetMetadata`	`object`	Additional context about the target (e.g., recipient, channel, file type). Stored for audit and notification purposes — not passed to rule evaluation. Policies evaluate against the `input` field.
`correlationId`	`string`	Your own request ID for tracing. Max 255 characters.
`callbackUrl`	`string`	Webhook URL to receive review decisions when enforcement requires manual approval. Max 1024 characters.
`sessionId`	`string`	UUID of an existing evaluation session to group this evaluation into.

The input field is intentionally flexible. Pass whatever structure makes sense for your use case:

// Chat message
{ "input": { "role": "assistant", "content": "Here is your account number: 1234567890" } }
 
// Email
{ "input": { "to": "external@example.com", "subject": "Q4 Report", "body": "..." } }
 
// Tool call
{ "input": { "tool": "send_email", "arguments": { "to": "...", "body": "..." } } }

Examples

curl

curl -X POST https://api.aguardic.com/v1/evaluate \
  -H "Authorization: Bearer ag_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "role": "assistant",
      "content": "Please send your SSN to verify your identity."
    },
    "targetKey": "chat-response"
  }'

TypeScript

const response = await fetch("https://api.aguardic.com/v1/evaluate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AGUARDIC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: {
      role: "assistant",
      content: "Please send your SSN to verify your identity.",
    },
    targetKey: "chat-response",
  }),
});
 
const result = await response.json();
 
if (result.data.outcome === "DENY") {
  console.log("Blocked:", result.data.violations);
} else {
  // Proceed with the action
}

Response

All Aguardic API responses are wrapped in {"success": true, "statusCode": 200, "data": ...}. The evaluation result is inside the data field.

Success Response

{
  "success": true,
  "statusCode": 200,
  "data": {
    "outcome": "DENY",
    "enforcementAction": "BLOCK",
    "evaluationRunId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reviewRequestId": null,
    "pollUrl": null,
    "sessionId": null,
    "violations": [
      {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
        "ruleId": "rule-1",
        "ruleName": "PII Detection",
        "severity": "HIGH",
        "resolvedAction": "BLOCK",
        "explanation": "Content contains social security reference",
        "field": "content",
        "snippet": "send your SSN"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`outcome`	`string`	Final evaluation result: `ALLOW`, `DENY`, or `FLAG`.
`enforcementAction`	`string`	The enforcement action applied: `ALLOW`, `WARN`, `BLOCK`, or `APPROVAL_REQUIRED`.
`evaluationRunId`	`string or null`	UUID of the evaluation run for audit trail purposes. `null` when no policies are bound.
`reviewRequestId`	`string or null`	Present when `enforcementAction` is `APPROVAL_REQUIRED`. Use this ID to check review status.
`pollUrl`	`string or null`	URL to poll for review decisions when approval is required.
`sessionId`	`string or null`	The session ID this evaluation belongs to. Returned when you provide a `sessionId` or when agent integrations auto-create one.
`violations`	`array`	List of policy violations found. Empty array when no violations are detected.

Violation Object

Field	Type	Description
`id`	`string`	Unique violation identifier.
`ruleId`	`string`	The ID of the policy rule that was violated.
`ruleName`	`string`	Human-readable name of the violated rule.
`severity`	`string or null`	Violation severity: `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
`resolvedAction`	`string or null`	The action resolved for this specific violation: `BLOCK`, `APPROVAL_REQUIRED`, `WARN`, or `LOG`.
`explanation`	`string or null`	Why this violation was triggered.
`field`	`string or null`	The input field that triggered the violation.
`snippet`	`string or null`	The relevant portion of content that caused the violation.

Behaviors

No Active Bindings

If no active policies are bound to your integration, the endpoint returns an immediate allow:

{
  "success": true,
  "statusCode": 200,
  "data": {
    "outcome": "ALLOW",
    "enforcementAction": "ALLOW",
    "evaluationRunId": null,
    "sessionId": null,
    "violations": []
  }
}

Approval Required

When a policy's enforcement mode is set to require manual approval, the response includes a reviewRequestId and pollUrl. Your application should poll the URL or provide a callbackUrl in the request to receive a webhook when the review is completed.

{
  "data": {
    "outcome": "DENY",
    "enforcementAction": "APPROVAL_REQUIRED",
    "reviewRequestId": "r1e2v3i4-e5w6-7890-abcd-ef1234567890",
    "pollUrl": "/v1/reviews/r1e2v3i4-e5w6-7890-abcd-ef1234567890",
    "violations": [...]
  }
}

Session Context

When you include a sessionId, Aguardic loads the session's accumulated context -- dataTags, toolsUsed, actionCount, and recentActions -- and passes it to the policy evaluation engine. This enables context-aware policies that consider the full history of a multi-step workflow, not just the current request.

Agent integrations automatically create a session if no sessionId is provided. The auto-created session ID is returned in the response.

Error Responses

{
  "statusCode": 401,
  "errors": [
    { "message": "Invalid or expired API key" }
  ]
}

Field	Type	Description
`400`	`HTTP status`	Invalid request body (missing `input` or validation failure)
`401`	`HTTP status`	Invalid or missing API key
`404`	`HTTP status`	Session not found (invalid `sessionId`)
`500`	`HTTP status`	Internal server error

Next Steps

Authentication -- Set up your API key
Sessions API -- Group evaluations into sessions for multi-step workflows
Evaluation Sessions Guide -- Learn session patterns and best practices

Authentication Sessions