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.

Step 1: Receive Your API Key¶

Your API key is provisioned by the AEGIS team during onboarding. You will receive:

• An API key (used in the X-Api-Key header)
• A base URL for your environment (dev, staging, or production)
• A tenant ID associated with 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://YOUR_API_URL/health

Expected response:

{
  "healthy": true,
  "stage": "dev",
  "config_ok": true,
  "gates_ok": true
}

If healthy is false, contact the AEGIS team before proceeding.

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://YOUR_API_URL/evaluate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: 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"
    }
  }
}

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://YOUR_API_URL/risk-check \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: 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 limit headers are included in every response:

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

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