AGEI

API Documentation

RESTful API reference for AGEI integration

Important: Evidence Submission Responsibility

API evidence submissions are only as reliable as the systems and controls that generate them. AGEI helps preserve event evidence and policy decisions, but organizations remain responsible for ensuring that integrations submit accurate, complete, and authorized data.

Base URL

https://your-domain.com/api/v1

All API endpoints are prefixed with /api/v1

Authentication

Using Supabase Auth with API keys

Headers Required

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Service Role Access

Use SUPABASE_SERVICE_ROLE_KEY for backend operations that bypass RLS.

Policy Gates

Evaluate Policy Gate

Submit evidence for policy evaluation

POST

Endpoint

/gates/evaluate

Request Body

{
  "organizationId": "uuid",
  "gateDefinitionId": "uuid",
  "policyVersionId": "uuid",
  "evidencePayload": {
    "accuracy": 0.97,
    "bias_score": 0.05,
    "model_name": "credit-risk-v2"
  }
}

Response (200 OK)

{
  "success": true,
  "evaluation": {
    "id": "uuid",
    "outcome": "approve",
    "reasonCode": "EVIDENCE_SATISFIES_POLICY",
    "passedRules": ["accuracy_threshold", "bias_limit"],
    "failedRules": []
  },
  "receipt": {
    "id": "uuid",
    "hash": "sha256:abc123..."
  }
}

HITL (Human-in-the-Loop)

Create HITL Request

Escalate decision to human reviewer

POST

Endpoint

/hitl/request

Request Body

{
  "organizationId": "uuid",
  "requestType": "model_deployment",
  "resourceType": "ai_model",
  "resourceId": "model-123",
  "riskClassification": "high",
  "requiredReviewerRole": "model_risk_reviewer",
  "policyReasonCode": "HIGH_RISK_MODEL_DEPLOYMENT",
  "evidenceSummary": {
    "model_name": "credit-risk-v2",
    "accuracy": 0.94,
    "bias_score": 0.12
  }
}

Response (201 Created)

{
  "success": true,
  "hitlRequestId": "uuid",
  "requestNumber": "HITL-001777652985",
  "status": "pending",
  "expiresAt": "2026-05-01T21:12:37Z",
  "approvalLink": "https://app.com/review/uuid?token=..."
}

Get Review Queue

List pending reviews for a reviewer

GET

Endpoint

/hitl/queue?status=active

Query Parameters

  • • status: active, pending, decided, expired, all
  • • reviewerRole: Filter by role
  • • riskLevel: low, medium, high, critical

Agent Governance

Start Agent Session

Create tracked agent session

POST

Endpoint

/agents/sessions

Request Body

{
  "organizationId": "uuid",
  "agentPrincipalId": "uuid",
  "sessionKey": "session-20260503-001",
  "workflowName": "customer_support",
  "sessionContext": {
    "customer_id": "cust-123",
    "issue_type": "billing"
  }
}

Evaluate Tool Request

Request permission to use agent tool

POST

Endpoint

/agents/tools/evaluate

Note

Critical-risk tools automatically trigger HITL workflow. Response includes HITL request details when escalated.

Agent Security

List Anomaly Alerts

Get security alerts for monitoring

GET

Endpoint

/agent-security/alerts?organizationId=uuid&status=open

Query Parameters

  • • organizationId (required)
  • • status: open, investigating, resolved, false_positive
  • • severity: low, medium, high, critical
  • • anomalyType: unusual_tool, volume_spike, etc.

Response (200 OK)

{
  "success": true,
  "alerts": [...],
  "statistics": {
    "total_alerts": 15,
    "open_alerts": 5,
    "critical_alerts": 2
  }
}

Rate Limits

Starter

1,000 requests/hour

Professional

10,000 requests/hour

Enterprise

Custom limits

Error Codes

400
Bad Request - Invalid parameters
401
Unauthorized - Invalid or missing API key
403
Forbidden - Insufficient permissions
404
Not Found - Resource doesn't exist
429
Too Many Requests - Rate limit exceeded
500
Internal Server Error - Server-side issue