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, WARN, or BLOCK) along with any policy violations.

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 | Required | Description | |-------|------|----------|-------------| | input | object | Yes | The content or action to evaluate. Pass whatever structure your integration uses -- there is no fixed schema. | | targetKey | string | No | Identifies the evaluation target (e.g., "chat", "email-send", "file-upload"). Max 1000 characters. | | targetMetadata | object | No | Additional context about the target (e.g., recipient, channel, file type). | | correlationId | string | No | Your own request ID for tracing. Max 255 characters. | | callbackUrl | string | No | Webhook URL to receive review decisions when enforcement requires manual approval. Max 1024 characters. | | sessionId | string | No | 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 === "BLOCK") {
  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": "BLOCK",
    "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, WARN, or BLOCK. | | enforcementAction | string | The enforcement action applied: ALLOW, WARN, BLOCK, or APPROVAL_REQUIRED. | | evaluationRunId | string | UUID of the evaluation run for audit trail purposes. | | reviewRequestId | string \| null | Present when enforcementAction is APPROVAL_REQUIRED. Use this ID to check review status. | | pollUrl | string \| null | URL to poll for review decisions when approval is required. | | sessionId | string \| 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 | Violation severity: LOW, MEDIUM, HIGH, or CRITICAL. | | resolvedAction | string | The action resolved for this specific violation: ALLOW, WARN, or BLOCK. | | explanation | string | Why this violation was triggered. | | field | string | The input field that triggered the violation. | | snippet | string | 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": "...",
    "reviewRequestId": null,
    "pollUrl": 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": "BLOCK",
    "enforcementAction": "APPROVAL_REQUIRED",
    "reviewRequestId": "r1e2v3i4-e5w6-7890-abcd-ef1234567890",
    "pollUrl": "https://api.aguardic.com/v1/review-requests/r1e2v3i4.../status",
    "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" }
  ]
}

| Status | Description | |--------|-------------| | 400 | Invalid request body (missing input or validation failure) | | 401 | Invalid or missing API key | | 404 | Session not found (invalid sessionId) | | 500 | 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