REST API reference.

Base URL

https://gateway.aegis.dev    # hosted
http://localhost:8080         # self-host / desktop

Authentication

# Org API key — for /api/v1/*
curl -H "X-AEGIS-API-Key: aeg_xxx" https://gateway.aegis.dev/api/v1/check

# Agent JWT — preferred for SDK-side identity
curl -H "X-AEGIS-Agent-Token: eyJhbG..." https://gateway.aegis.dev/api/v1/check

# SCIM bearer — for IdP user provisioning at /scim/v2/*
curl -H "Authorization: Bearer scim_xxx" https://gateway.aegis.dev/scim/v2/Users

Core endpoints

POST /api/v1/check

Gate a single tool call. Returns allow / block / pending.

POST /api/v1/check
{
  "agent_id":  "my-agent",
  "tool_name": "db_query",
  "arguments": { "sql": "SELECT 1" }
}

→ 200 OK
{
  "decision":         "allow",
  "policy_name":      "sql-injection",
  "risk_level":       "LOW",
  "classification":   { "category": "database", "signals": [] },
  "anomaly_score":    0.12,
  "check_id":         "..."
}

GET /api/v1/check/:id/decision

Poll a pending check (blocking mode). Returns latest verdict + decided_by.

PATCH /api/v1/check/:id

Human reviewer resolves a pending check. Body: { "decision": "allow" | "block", "decided_by": "alice@acme.com" }.

POST /api/v1/traces

Ingest a tool-call trace (SDK uses this). Async — returns 201 immediately.

GET /api/v1/traces

List traces with filtering: ?agent_id= &from= &to= &blocked=true &limit= &offset=.

Policies

GET /api/v1/policies

List policies including platform defaults + this tenant's overrides.

POST /api/v1/policies

Create a policy. Body: { id, name, description, policy_schema, risk_level }. AJV schema or template.

DELETE /api/v1/policies/:id

Remove. Audited automatically.

Anomalies + audit

GET /api/v1/anomalies

Layer-2 events. ?min_score=0.7 &agent_id= &decision=block.

GET /api/v1/audit-log

Admin audit log — every policy create / update / delete / kill-switch / config write. Filter by ?action= &resource_type= &q= substring.

Transparency log

GET /api/v1/transparency-log/size

Current Merkle tree size.

GET /api/v1/transparency-log/sth

Signed tree head — anchor for offline verification.

GET /api/v1/transparency-log/proof/:leaf_index

Inclusion proof for a specific leaf. Verifiable with the zero-dep CLI under tools/verify-log/.

SCIM 2.0 (RFC 7644)

For IdP user / group provisioning. All standard SCIM verbs:

• GET /scim/v2/Users · POST /scim/v2/Users · PATCH /scim/v2/Users/:id · DELETE /scim/v2/Users/:id
• GET /scim/v2/Groups · POST /scim/v2/Groups · PATCH /scim/v2/Groups/:id
• GET /scim/v2/ServiceProviderConfig · GET /scim/v2/ResourceTypes · GET /scim/v2/Schemas

Filter syntax: userName eq "alice@acme.com" / active eq false / email co "@acme" / etc.

Billing (Stripe webhook)

POST /api/v1/stripe/webhook

Stripe → AEGIS lifecycle sync. Signature-verified. Handles customer.subscription.created / .updated / .deleted + invoice.payment_succeeded / .failed.

Health + metrics

• GET /health — JSON: status, version, uptime, db reachable.
• GET /ready — 200 when accepting traffic; 503 otherwise.
• GET /metrics — Prometheus exposition. Not traced for OTel (cardinality + scrape noise).

Errors

All errors are JSON: { "error": { "code", "message", ...detail } }. Standard codes:

• UNAUTHORIZED · FORBIDDEN · RATE_LIMITED (with Retry-After)
• VALIDATION_ERROR (with details: [...] from Zod)
• POLICY_VIOLATION (with policy_name, counterfactual hint)
• PROXY_UPSTREAM_FAILED / PROXY_UPSTREAM_TIMEOUT

Next

• Docs index
• SDK reference
• Policy DSL + templates