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.

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

Sign up at portal.undercurrentholdings.com to create your account and generate API keys instantly. Enterprise customers can also be provisioned by the AEGIS team during onboarding.

You will receive:

• 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 Endpoint

The health endpoint requires no authentication and confirms the service is operational:

curl https://aegis-api-980022636831.us-central1.run.app/health

Expected response:

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

If status is "degraded", check the checks object for details and 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 — production deployments require a commercial subscription at portal.undercurrentholdings.com.

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://aegis-api-980022636831.us-central1.run.app/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://aegis-api-980022636831.us-central1.run.app/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