Developer API

Agent Firewall API

Put MAX-AI Guard in the pre-action path for autonomous agents. Demo evaluation explains policy; production authorization returns a canonical request and short-lived, single-use execution grant.

Try demo Create API key

Copy-paste demo cURL

This unauthenticated endpoint is an isolated policy simulation. It never returns an execution grant and cannot authorize a tool call.

curl -X POST https://max-ai-guard.vercel.app/api/v1/evaluate \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-donor-email-001" \
  -d '{
    "actor": { "agent_id": "agent_demo_firewall", "role": "MEMBER" },
    "action": {
      "type": "SEND_EXTERNAL_EMAIL",
      "target": "Sensitive donor update",
      "tool_name": "gmail.send",
      "external_effect": true,
      "recipients": ["donor@example.org"],
      "data_classes": ["donor_data", "program_data"],
      "content_preview": "Draft and send a donor update using program metrics."
    },
    "context": { "environment": "demo", "source": "manual", "tenant_id": "tenant_demo" }
  }'

Decision statuses

ALLOW

Eligible for a signed grant; execute only after single-use verification.

DENY

Block the action before execution.

REQUIRES_APPROVAL

Pause and route to the approval workflow.

REDACT

Remove sensitive content before the action continues.

QUARANTINE

Isolate the action because regulated or disallowed data is involved.

Production cURL

Production authorization always requires an API key whose owner has exactly one active registered agent. Identity, role, tenant, environment, and external-effect classification are bound on the server.

curl -X POST https://<your-deployment>/api/v1/guard/authorize \
  -H "Authorization: Bearer mg_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: action-123" \
  -d '{
    "actor": { "agent_id": "agent_support_01", "role": "MEMBER" },
    "action": {
      "type": "SEND_EXTERNAL_EMAIL",
      "target": "donor update",
      "tool_name": "gmail.send",
      "external_effect": true,
      "recipients": ["donor@example.org"],
      "data_classes": ["donor_data", "program_data"],
      "content_preview": "Draft a donor update with program metrics."
    },
    "context": { "environment": "production", "source": "sdk" }
  }'

TypeScript guard wrapper

const authorizationResponse = await fetch("https://<your-deployment>/api/v1/guard/authorize", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MAXAI_GUARD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    actor: { agent_id: "agent_coding", role: "MEMBER" },
    action: {
      type: "RUN_SHELL_COMMAND",
      tool_name: "shell.exec",
      parameters: { command: "rm -rf /production-data" },
      external_effect: true,
    },
    context: { environment: "production", source: "sdk" },
  }),
});

const authorization = await authorizationResponse.json();
if (authorization.status !== "ALLOW" || !authorization.execution_grant) {
  throw new Error(authorization.status);
}

const verification = await fetch("https://<your-deployment>/api/v1/guard/verify", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MAXAI_GUARD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    execution_grant: authorization.execution_grant,
    request: authorization.canonical_request,
  }),
}).then((result) => result.json());

if (!verification.valid) throw new Error(verification.reason);
await tool.execute(verification.canonical_request.action.parameters);

Python guard wrapper

import os, requests

payload = {
  "actor": {"agent_id": "agent_research", "role": "REVIEWER"},
  "action": {
    "type": "READ_DOCUMENT",
    "target": "Program overview",
    "data_classes": ["program_data"],
    "external_effect": False,
  },
  "context": {"environment": "production", "source": "sdk"},
}

decision = requests.post(
  "https://<your-deployment>/api/v1/guard/authorize",
  headers={"Authorization": f"Bearer {os.environ['MAXAI_GUARD_API_KEY']}"},
  json=payload,
  timeout=10,
).json()

Response

{
  "decision_id": "decision_abc123",
  "receipt_id": "receipt_def456",
  "status": "REQUIRES_APPROVAL",
  "risk_level": "HIGH",
  "reasons": ["External communication with donor, grant, or program data requires reviewer approval."],
  "policy_matches": ["policy.external_comms_sensitive_data"],
  "approval_url": "/approvals?decision=decision_abc123",
  "audit_event_id": "audit_ghi789"
}

Integration pattern

Agent proposes action.
Call authorize with metadata, data classes, recipients, tool name, and minimal content preview.
Use the returned canonical_request; do not execute caller-original data.
If ALLOW, verify and atomically consume its execution_grant immediately before the tool call.
If REQUIRES_APPROVAL, pause and poll or receive a webhook.
If DENY, do not execute.
Store receipt_id for audit review. A consumed or replayed grant cannot execute again.

Webhook example

POST https://your-app.example/maxai-approval-webhook
{
  "event": "approval.decided",
  "decision_id": "decision_abc123",
  "receipt_id": "receipt_def456",
  "status": "APPROVED",
  "reviewer_role": "REVIEWER",
  "decided_at": "2026-07-04T12:30:00.000Z"
}

Receipt example

{
  "receipt_id": "receipt_def456",
  "tenant_id": "tenant_acme",
  "action_id": "action_123",
  "action": {
    "type": "SEND_EXTERNAL_EMAIL",
    "external_effect": true,
    "data_classes": ["donor_data", "program_data"]
  },
  "decision": {
    "status": "REQUIRES_APPROVAL",
    "risk_level": "HIGH",
    "policy_matches": ["policy.external_comms_sensitive_data"]
  },
  "integrity": {
    "receipt_hash": "..."
  }
}