REST API Integration

Overview

The REST API integration is the most flexible way to add governance to any application. Create an integration, bind policies to it, and call the evaluate endpoint with whatever content you want to check. There is no SDK required -- all examples use fetch() or curl.

Use it for custom applications, microservices, CI/CD pipelines, form validation, content moderation, or any workflow where you need policy evaluation.

Setup

1. Create a REST API Integration

Navigate to Integrations in the Aguardic dashboard, click Add Integration, and select REST API. Give it a name (e.g., "Production API" or "Content Pipeline").

When the integration is created, you'll receive an API key. Copy it immediately.

2. Bind Policies

Go to Policy Bindings and bind one or more policies to your REST API integration. Only policies actively bound to the integration are evaluated when you call the endpoint.

3. Call the Evaluate Endpoint

Send content to POST /v1/evaluate with your API key in the Authorization header.

Evaluate Endpoint

POST https://api.aguardic.com/v1/evaluate

Authentication

Include your API key as a Bearer token:

Authorization: Bearer ag_live_abc123def456

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | input | object | Yes | The content to evaluate. Pass any key-value structure -- there is no fixed schema. | | targetKey | string | No | Identifies the action being evaluated (e.g., "chat-response", "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. | | sessionId | string | No | UUID of an existing evaluation session to group related evaluations. |

The input field is intentionally flexible. Pass whatever structure matches your use case.

curl Example

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

TypeScript Example

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: {
      content: "Please send your SSN to verify your identity",
      recipient: "external-user@example.com",
    },
    targetKey: "chat-response",
  }),
});
 
const { data } = await response.json();
 
if (data.outcome === "BLOCK") {
  console.log("Blocked:", data.violations);
} else {
  console.log("Allowed");
}

Response Handling

All API responses are wrapped in { success, statusCode, 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"
      }
    ]
  }
}

Handling Each Outcome

const { data } = await response.json();
 
switch (data.outcome) {
  case "ALLOW":
    // No violations -- proceed normally
    break;
 
  case "WARN":
    // Violations found but action is allowed
    console.warn("Policy warnings:", data.violations);
    // Proceed, but consider logging for review
    break;
 
  case "BLOCK":
    // Action is blocked
    console.error("Blocked by policy:", data.violations);
    // Do not proceed
    break;
}
 
// Handle APPROVAL_REQUIRED separately via enforcementAction
if (data.enforcementAction === "APPROVAL_REQUIRED") {
  // Action is held for manual review
  console.log("Awaiting approval:", data.reviewRequestId);
  // Poll data.pollUrl or use callbackUrl for async notification
}

No Active Bindings

If no policies are bound to your integration, the endpoint returns an immediate allow with an empty violations array.

Use Cases

• Custom applications -- Evaluate user-generated content, form submissions, or API payloads before processing
• Microservices -- Add governance checks at service boundaries without modifying core logic
• CI/CD pipelines -- Validate configuration files, deployment manifests, or release notes during builds
• Content moderation -- Screen messages, comments, or uploads against organizational policies
• Data pipelines -- Check data transformations or ETL outputs for compliance violations

Next Steps

• Evaluate API Reference -- Full endpoint documentation with all response fields
• Evaluation Sessions -- Group related evaluations for multi-step workflows
• Your First Policy -- Create and configure policies