Customer Onboarding

This guide walks you through integrating with the AEGIS Governance REST API, from your first health check to a fully automated governance gate.

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

What You'll Accomplish

By the end of this guide, you will have:

• Verified connectivity to the AEGIS API
• Submitted your first proposal evaluation and received a structured decision
• Understood the response format (status, confidence, gate results, audit ID)
• Chosen an integration method for your environment (SDK, CLI, or REST)

Step 1: Get Your API Key

API keys were issued at portal.undercurrentholdings.com. A key does not restore evaluation while the hosted service is offline.

A provisioned account had:

• An API key (used in the Authorization: Bearer header)
• A base URL for your environment (dev, staging, or production)
• A customer ID (cust_...) identifying your organization

Keep your API key confidential. Do not commit it to source control or embed it in client-side code. Store it in a secrets manager or environment variable.

Step 2: Test the Health and Readiness Endpoints

Both endpoints require no authentication. /health is a fast liveness probe; /ready is the deep readiness probe (DB, audit chain, Unkey wiring) used by the deploy gate.

curl https://api.aegis.undercurrentholdings.com/health

Expected response:

{
  "status": "ok",
  "version": "1.1.0",
  "stage": "production",
  "runtime": "cloud-run",
  "checks": {
    "config": { "ok": true }
  }
}

For deeper validation that the service is correctly wired to its dependencies, query /ready:

curl https://api.aegis.undercurrentholdings.com/ready

Expected status is "ready" with all four probes (db, schema, audit_chain, unkey) reporting ok: true. A 503 response means one or more probes failed — the response body's checks map identifies which.

If /health returns "degraded" or /ready returns 503, contact the AEGIS team before proceeding.

Note: The health endpoint confirms current operational status but does not constitute a service-level agreement (SLA). Production SLA terms, if applicable, are specified in your service agreement. AEGIS is licensed under BSL 1.1 — see the license for production-use terms.

Step 3: Make Your First Evaluation

Send a POST request to the /evaluate endpoint with your API key and a proposal payload:

curl -X POST https://api.aegis.undercurrentholdings.com/evaluate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "proposal_summary": "Add Redis caching layer to reduce API latency",
    "estimated_impact": "medium",
    "risk_proposed": 0.3,
    "risk_baseline": 0.1,
    "complexity_score": 0.6,
    "quality_score": 0.8,
    "novelty_score": 0.4
  }'

Step 4: Understand the Response

A successful evaluation returns a JSON object describing the governance decision:

{
  "status": "proceed",
  "confidence": 0.87,
  "gates_passed": 5,
  "gates_failed": 0,
  "failing_gates": [],
  "rationale": "All gates passed. Proposal is within acceptable risk and complexity bounds.",
  "next_steps": [
    "Proceed with implementation",
    "Monitor drift metrics post-deployment"
  ],
  "constraints": [],
  "decision_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-02-24T12:00:00+00:00",
  "override_eligible": false,
  "override_requires": [],
  "gates": {
    "risk": {
      "passed": true,
      "value": 0.1200,
      "threshold": 0.9500,
      "confidence": 0.87,
      "message": "Risk delta within acceptable bounds"
    },
    "complexity": {
      "passed": true,
      "value": 0.6000,
      "threshold": 0.5000,
      "confidence": null,
      "message": "Complexity above floor"
    }
  }
}

Note: Only two gates are shown for brevity. The full response includes all six gates (risk, profit, novelty, complexity, quality, utility).

Key fields

Status codes

Step 5: Integrate into Your Workflow

Choose the integration method that fits your environment:

• Python SDK — for applications and scripts written in Python. See the Python SDK Quickstart.

• CLI — for shell scripts and CI/CD pipelines. See the CLI Quickstart.

• REST API — for any language or platform that can make HTTP requests. Use the patterns shown above.

Quick Risk Check (REST)

For lightweight, non-Bayesian threshold checks, use the /risk-check endpoint:

curl -X POST https://api.aegis.undercurrentholdings.com/risk-check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "my-service",
    "action_description": "Update config file",
    "risk_score": 0.2
  }'

Note: /risk-check performs a direct threshold comparison without Bayesian posterior evaluation. Use /evaluate for decisions that require full gate analysis and audit trails.

Rate Limits

Rate limiting is enforced per API key via Unkey. Limits vary by tier:

Rate limits are current as of 2026-04-05 and subject to change. Check your account dashboard at portal.undercurrentholdings.com for live limits.

If you exceed your tier's limit, you will receive a 429 Too Many Requests response. Implement exponential backoff in your client.

Tier-Gated Features

Most AEGIS features are available to all tiers. The following require specific tiers:

All other features (6 gates, /evaluate, /risk-check, /sandbox/evaluate, MCP tools, SDK, JSON export, drift monitoring) are available to all tiers including Community.

Support

Next Steps

• Installation — install the SDK or CLI locally
• Python SDK Quickstart — programmatic integration
• CLI Quickstart — command-line integration
• Parameter Reference — complete parameter documentation
• Domain Templates — integration templates for trading, CI/CD, moderation, and agents