Skip to content

REST API Quickstart

Get started with the AEGIS Governance REST API in under five minutes.

Prerequisites

  • An API key (see Onboarding for how to obtain one)
  • curl (or any HTTP client)

Base URL

Environment URL
Dev https://yd1xm4ahcg.execute-api.us-west-2.amazonaws.com/dev
Prod Contact your administrator for the production endpoint

1. Health Check (no authentication required)

Verify the API is reachable and all subsystems are operational:

curl -s https://yd1xm4ahcg.execute-api.us-west-2.amazonaws.com/dev/health \
  | python3 -m json.tool

Expected response (HTTP 200):

{
  "status": "ok",
  "version": "1.0.0",
  "stage": "dev",
  "checks": {
    "config": { "ok": true },
    "gates":  { "ok": true }
  }
}

A 503 response with "status": "degraded" means one or more subsystems failed their self-test. Check the checks object for details.

2. Evaluate a Proposal

Submit a proposal for full governance evaluation through all six Bayesian gates (risk, profit, novelty, complexity, quality, utility):

curl -s -X POST \
  https://yd1xm4ahcg.execute-api.us-west-2.amazonaws.com/dev/evaluate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "proposal_summary": "Increase allocation to momentum factor by 15%",
    "estimated_impact": "high",
    "agent_id": "trading-agent-001",
    "phase": "plan",
    "risk_baseline": 0.10,
    "risk_proposed": 0.25,
    "profit_baseline": 0.05,
    "profit_proposed": 0.12,
    "novelty_score": 0.6,
    "complexity_score": 0.4,
    "quality_score": 0.8,
    "quality_subscores": [0.85, 0.75, 0.80],
    "requires_human_approval": false,
    "time_sensitive": true,
    "reversible": true,
    "metadata": {
      "strategy": "momentum",
      "asset_class": "equity"
    }
  }' | python3 -m json.tool

Example response (HTTP 200):

{
  "status": "escalate",
  "confidence": 0.88,
  "gates_passed": 4,
  "gates_failed": 2,
  "failing_gates": ["risk", "utility"],
  "rationale": "High impact proposal with failing gates: risk, utility",
  "next_steps": [
    "Escalate to Risk Lead for review",
    "Prepare justification document"
  ],
  "constraints": [],
  "decision_id": "d4e5f6a7-b8c9-4d0e-a1f2-b3c4d5e6f7a8",
  "timestamp": "2026-02-24T14:30:00+00:00",
  "override_eligible": true,
  "override_requires": ["risk_lead", "security_lead"],
  "gates": {
    "risk":       { "passed": false, "value": 0.15, "threshold": 0.95, "confidence": 0.88, "message": null },
    "profit":     { "passed": true,  "value": 0.07, "threshold": 0.95, "confidence": 0.92, "message": null },
    "novelty":    { "passed": true,  "value": 0.6,  "threshold": 0.5,  "confidence": null, "message": null },
    "complexity": { "passed": true,  "value": 0.4,  "threshold": 0.3,  "confidence": null, "message": null },
    "quality":    { "passed": true,  "value": 0.8,  "threshold": 0.7,  "confidence": null, "message": null },
    "utility":    { "passed": false, "value": 0.0,  "threshold": 0.0,  "confidence": null, "message": "Utility LCB below threshold" }
  },
  "_tenant_id": "abc123",
  "_request_id": "req-456"
}

The status field tells you what to do next:

Status Meaning
proceed Safe to continue
pause Awaiting human review
halt Stop immediately
escalate Escalate to higher authority

3. Quick Risk Check

For lightweight pre-flight checks that do not need the full gate pipeline:

curl -s -X POST \
  https://yd1xm4ahcg.execute-api.us-west-2.amazonaws.com/dev/risk-check \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "risk_score": 0.2,
    "threshold": 0.5,
    "agent_id": "ci-agent-007",
    "action_description": "Run lint checks on feature branch"
  }' | python3 -m json.tool

Expected response (HTTP 200):

{
  "safe": true,
  "risk_score": 0.2,
  "threshold": 0.5,
  "agent_id": "ci-agent-007",
  "_tenant_id": "abc123",
  "_request_id": "req-101"
}

safe is true when risk_score < threshold, false otherwise.

Note: This endpoint performs a simple threshold comparison and does NOT compute Bayesian posterior probabilities. For auditable governance decisions, use POST /evaluate.

4. Minimal Evaluate Request

Every field in the evaluate request body has a server-side default. The smallest valid request is an empty JSON object:

curl -s -X POST \
  https://yd1xm4ahcg.execute-api.us-west-2.amazonaws.com/dev/evaluate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{}' | python3 -m json.tool

This evaluates a proposal with all default values (medium impact, plan phase, zero risk/profit deltas, etc.).

Next Steps