API Documentation

Complete reference for the QAE Safety Certification API by Northbeam Solutions.

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer qae_your_api_key_here

Get a free API key by signing up at POST /portal/auth/signup or from the home page.

Portal Endpoints

POST /portal/auth/signup

Create a new account and receive a Free-tier API key.

// Request
{
  "email": "developer@example.com"
}

// Response (200)
{
  "user_id": "usr_abc123...",
  "api_key": "qae_def456...",
  "tier": "Free"
}

POST /portal/auth/login

Obtain a JWT token for session-based authentication.

// Request
{
  "email": "developer@example.com"
}

// Response (200)
{
  "token": "eyJhbGciOi...",
  "user_id": "usr_abc123..."
}

GET /portal/auth/keys

List API keys for the authenticated user. Requires Authorization header.

POST /portal/auth/keys/rotate

Rotate an existing API key. Returns a new key with the same tier.

// Request
{
  "current_key": "qae_old_key..."
}

// Response (200)
{
  "new_api_key": "qae_new_key...",
  "tier": "Pro"
}

GET /portal/usage

Retrieve usage statistics for the authenticated API key.

// Response (200)
{
  "usage": {
    "calls_today": 42,
    "calls_month": 580,
    "avg_latency_ms": 23.4,
    "last_request_at": "2026-03-13T14:22:00Z"
  },
  "quota_status": "ok",
  "tier": "Free"
}

POST /portal/checkout

Create a Stripe checkout session for upgrading to Pro or Enterprise. Returns a URL to redirect the user.

// Request
{
  "tier": "pro"
}

// Response (200)
{
  "url": "https://checkout.stripe.com/c/pay/..."
}

Certification Endpoints

POST /api/v2/certify

Safety kernel certification for agent actions. Evaluates the proposed action against 5 constraint channels and returns a deterministic safety certificate.

// Request
{
  "action_id": "trade-001",
  "agent_id": "agent-alpha",
  "state_deltas": [
    { "dimension": "market_risk", "from_value": 0.3, "to_value": 0.5 }
  ],
  "priority": "standard",
  "portfolio": { "id": "p1", "name": "Main", "positions": [...], "base_currency": "USD", "as_of": "..." },
  "market_data": { "as_of": "...", "prices": {...}, "volatilities": {...}, "risk_free_rate": 0.05, ... }
}

// Response (200)
{
  "certificate_id": "cert-ae284154...",
  "action_id": "trade-001",
  "agent_id": "agent-alpha",
  "decided_at": "2026-03-15T12:00:00Z",
  "decision": "CERTIFIED",          // CERTIFIED | CERTIFIED_WITH_WARNING | ESCALATE_TO_HUMAN | BLOCKED
  "zone": "SAFE",                    // SAFE | CAUTION | DANGER
  "margins": {
    "market_risk": 0.65,
    "credit_risk": 1.0,
    "liquidity_risk": 0.82,
    "concentration_risk": 0.45,
    "regulatory_capital": 0.95
  },
  "binding_constraint": "concentration_risk",
  "drift_budget": 0.45,
  "deterministic_hash": "ae284154e186...",
  "supplementary_analysis": {        // Present when advanced analysis features are enabled
    "binding_constraints": [
      { "channel": "concentration_risk", "margin": 0.45 },
      { "channel": "market_risk", "margin": 0.65 }
    ],
    "smooth_aggregate": 0.42,
    "time_to_boundary": null,
    "sensitivity_weights": [0.55, 0.25, 0.1, 0.05, 0.05]
  }
}

Response Headers

Every /api/v2/certify response includes these headers:

WebSocket Endpoint

GET /ws

Real-time risk certification over WebSocket. Supports portfolio subscriptions and streaming market updates.

// Connect
const ws = new WebSocket("wss://api.qaesubstrate.com/ws");

// Subscribe to portfolio updates
ws.send(JSON.stringify({
  "type": "subscribe",
  "portfolio_id": "p1",
  "portfolio": { ... },
  "market_data": { ... }
}));

// Certify an action in real time
ws.send(JSON.stringify({
  "type": "certify_action",
  "action_id": "rt-001",
  "agent_id": "agent-1",
  "state_deltas": [{ "dimension": "market_risk", "from_value": 0.3, "to_value": 0.5 }],
  "portfolio": { ... },
  "market_data": { ... }
}));

// Message types: subscribe, update_positions, market_tick, certify_action, unsubscribe, ping
// Server sends: certificate_update, safety_certificate, zone_transition, pong, error

WebSocket connections require an API key. Max 1,000 concurrent connections. Per-connection rate limit: 20 messages/second.

Observability

GET /metrics

Prometheus-compatible metrics endpoint (no auth required). Useful for monitoring your integration's performance and the platform's operational state. Returns text/plain in Prometheus exposition format.

Key metrics for integrators:

Health Endpoints

GET /health

API server health check (no auth required). Returns database connectivity status.

// Response (200)
{ "status": "ok", "version": "0.2.0", "checks": { "database": "ok" } }

GET /api/v2/health

Safety kernel health check (no auth required).

Error Handling

All errors return a JSON body with error, code, and request_id fields:

{
  "error": "Monthly quota exceeded for your tier. Upgrade for higher limits.",
  "code": "QUOTA_EXCEEDED",
  "request_id": "req-00000042"
}

HTTP status codes:

Error codes:

Rate Limits & Billing

At 95% quota usage, the /portal/usage response includes "upgrade_suggested_tier": "Pro" with a Stripe Checkout URL via POST /portal/checkout.

When quota is exceeded, responses include X-Quota-Remaining: 0 and Retry-After: <seconds> headers.

Quickstart

Get your first certification in under a minute.

curl

# 1. Sign up for an API key
API_KEY=$(curl -s -X POST https://api.qaesubstrate.com/portal/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}' | jq -r '.api_key')

# 2. Certify an action
curl -s -X POST https://api.qaesubstrate.com/api/v2/certify \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action_id": "test-001",
    "agent_id": "my-agent",
    "state_deltas": [{"dimension": "market_risk", "from_value": 0.3, "to_value": 0.5}],
    "portfolio": {"id":"p1","name":"Test","positions":[
      {"id":"P1","ticker":"AAPL","asset_type":"Equity","currency":"USD",
       "quantity":100,"market_value":50000,"weight":0.5,"factor_exposures":[1.0,0.2]},
      {"id":"P2","ticker":"MSFT","asset_type":"Equity","currency":"USD",
       "quantity":100,"market_value":50000,"weight":0.5,"factor_exposures":[0.9,0.3]}
    ],"base_currency":"USD","as_of":"2026-03-15T12:00:00Z"},
    "market_data": {"as_of":"2026-03-15T12:00:00Z","prices":{"AAPL":175,"MSFT":420},
      "returns":{"AAPL":[0.01,-0.005],"MSFT":[0.008,-0.002]},
      "volatilities":{"AAPL":0.25,"MSFT":0.22},"risk_free_rate":0.05,
      "credit_spreads":{},"fx_rates":{}}
  }'

Python

import requests

BASE = "https://api.qaesubstrate.com"

# 1. Sign up
key = requests.post(f"{BASE}/portal/auth/signup",
    json={"email": "you@example.com"}).json()["api_key"]

# 2. Certify
cert = requests.post(f"{BASE}/api/v2/certify",
    headers={"Authorization": f"Bearer {key}"},
    json={
        "action_id": "test-001", "agent_id": "my-agent",
        "state_deltas": [{"dimension": "market_risk", "from_value": 0.3, "to_value": 0.5}],
        "portfolio": {"id": "p1", "name": "Test", "positions": [
            {"id": "P1", "ticker": "AAPL", "asset_type": "Equity", "currency": "USD",
             "quantity": 100, "market_value": 50000, "weight": 0.5, "factor_exposures": [1.0, 0.2]}
        ], "base_currency": "USD", "as_of": "2026-03-15T12:00:00Z"},
        "market_data": {"as_of": "2026-03-15T12:00:00Z", "prices": {"AAPL": 175},
            "returns": {"AAPL": [0.01, -0.005]}, "volatilities": {"AAPL": 0.25},
            "risk_free_rate": 0.05, "credit_spreads": {}, "fx_rates": {}}
    }).json()

print(f"Decision: {cert['decision']}, Zone: {cert['zone']}")
print(f"Margins: {cert['margins']}")

Python (PyPI package)

# pip install qae-safety
from qae_safety import SafetyCertifier, SimpleAction, StateDelta, CertifierConfig

certifier = SafetyCertifier(CertifierConfig())
action = SimpleAction(
    action_id="test-001", agent_id="my-agent",
    state_deltas=[StateDelta(dimension="budget", from_value=0, to_value=25)]
)
cert = certifier.certify(action)
print(f"Decision: {cert.decision}, Zone: {cert.zone}")