Hosted service offline; see undercurrentholdings.com/status
AEGISdocs
Advisor (questionnaire)Product Status
Getting Started

REST API Quickstart

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

Hosted service offline. The hosted AEGIS API is offline (September 2026), so the requests below document the interface; they do not succeed today. Status: undercurrentholdings.com/status.

Prerequisites

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

Base URL

EnvironmentURL
Devhttps://api.aegis.undercurrentholdings.com
ProdContact your administrator for the production endpoint

1. Liveness and Readiness Checks (no authentication required)

Verify the API is reachable. AEGIS exposes two probes: /health is a fast liveness check (process is alive); /ready is the deep readiness probe (DB, schema, audit chain, Unkey wiring) and is what the deploy workflow uses as its post-deploy gate.

# Liveness — fast, returns 200 if config loads
curl -s https://api.aegis.undercurrentholdings.com/health \
  | python3 -m json.tool

Expected response (HTTP 200):

{
  "status": "ok",
  "version": "1.1.0",
  "stage": "production",
  "runtime": "cloud-run",
  "checks": {
    "config": { "ok": true }
  }
}
# Readiness — deeper, returns 200 only when all dependencies are wired
curl -s https://api.aegis.undercurrentholdings.com/ready \
  | python3 -m json.tool

Expected response (HTTP 200):

{
  "status": "ready",
  "db_kind": "postgres",
  "uptime_sec": 142,
  "checks": {
    "db":          { "ok": true, "latency_ms": 12, "error_class": null },
    "schema":      { "ok": true, "latency_ms": 4,  "error_class": null },
    "audit_chain": { "ok": true, "latency_ms": 18, "error_class": null },
    "unkey":       { "ok": true, "latency_ms": 0,  "error_class": null }
  }
}

A 503 response on either endpoint means a subsystem failed its self-test. Check the checks object for the failing probe and the identifier-shaped error_class (e.g., OperationalError, TimeoutError, MissingTable_aegis_customers).

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://api.aegis.undercurrentholdings.com/evaluate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 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.8,
    "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": "cust_a1b2c3d4e5f6",
  "_customer_id": "cust_a1b2c3d4e5f6",
  "_tier": "community",
  "_request_id": "req-456"
}

The status field tells you what to do next:

StatusMeaning
proceedSafe to continue
pauseAwaiting human review
haltStop immediately
escalateEscalate 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://api.aegis.undercurrentholdings.com/risk-check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 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": "cust_a1b2c3d4e5f6",
  "_customer_id": "cust_a1b2c3d4e5f6",
  "_tier": "community",
  "_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://api.aegis.undercurrentholdings.com/evaluate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 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

Installation

Install AEGIS and choose your integration method — Python SDK, REST API, or self-hosted source install.

Python SDK Quickstart

Walk through your first governance evaluation using the AEGIS Python SDK.

On this page

PrerequisitesBase URL1. Liveness and Readiness Checks (no authentication required)2. Evaluate a Proposal3. Quick Risk Check4. Minimal Evaluate RequestNext Steps