Base URL & Authentication

All endpoints are under https:///api/v1. Authentication uses Authorization: Bearer where the token is either an OIDC JWT or a Personal Access Token (PAT). Endpoints marked Public require no token.

bash

Issue a Personal Access Token

1# PATs are the recommended auth method for CI/CD and SDK usage
2curl -X POST https://sovereign.yourcompany.com/api/v1/auth/tokens \
3  -H "Authorization: Bearer $OIDC_JWT" \
4  -H "Content-Type: application/json" \
5  -d '{ "name": "CI pipeline", "expires_in_days": 90 }'
6# Returns { "token": "sk-sovereign-..." } — store immediately, shown once

Endpoint Groups

The API is organised into functional groups. All write operations emit an immutable audit entry.

Group	Path prefix	Key operations
Authentication	`/auth/*`	PAT issuance, IdP provider list
SCIM 2.0	`/api/scim/v2/*`	User provisioning, soft-delete, group sync
Model Registry	`/registry/models/*`	Register, promote, revert, champion/challenger split, model cards
External Providers	`/registry/providers/*`	SageMaker, Azure ML, Databricks, Vertex AI sync
LLM Gateway	`/gateway/v1/*`	Chat, completions, embeddings (OpenAI-compatible); PII/PHI routing
LLM Management	`/llm/*`	Providers, usage analytics, per-team cost chargeback, safety evals
AI Governance Agents	`/agents/*`	Graphs, runs, traces, memory, HITL resume; 4 autonomous agents
Compliance	`/compliance/*`	Real-time score, check, patch
Regulatory Frameworks	`/regulatory/*`	Evaluate against 7 frameworks, artifacts, workflow sign-off, reports
EU AI Act	`/models/:id/eu-ai-act/*`	Annex III classification, Annex IV documentation (json/markdown), production-readiness gate
Bias Evaluation	`/bias/*`	DIR, SPD, intersectional analysis, demographic parity
Adversarial Robustness	`/robustness/*`	FGSM, PGD, Carlini-Wagner, DeepFool, Square Attack
AI Safety Platform	`/safety/*`	Safety Policy Engine (validate input/output), ML classifier ensemble, Agentic Guard (tool-call + delegation validation), PII masking, multimodal image safety, cross-turn conversation monitor, Approvals review queue, Safety SLOs + burn-rate alerting, safety analytics dashboard / metrics / alerts, Red-Team certification runner, ModelSafetyRegistry clearance gate, Regulatory Report generation
Policy Center	`/policies/*`	OPA/Rego bundles, git sync, policy evaluation on every action
Audit Log	`/audit/*`	List, export CSV, verify SHA-256 chain, SIEM push test
GitOps	`/gitops/*`	Apply manifests, diff, sync, compliance_eval_id binding
Drift Detection	`/drift/*`	PSI baseline, drift check (alert ≥0.10, critical ≥0.25), kill switch
Kill Switch	`/models/:id/kill`	Remove model from all traffic in <2s; revert to champion
Federated Learning	`/federation/*`	Configs, rounds, participant management, aggregation
MCP Server	`/mcp/*`	31 governance tools for Claude Code / Desktop — 16 original + 15 Safety tools
Data Sources	`/data-sources/*`	Register Snowflake, BigQuery, S3, GCS, PostgreSQL
Retention / GDPR	`/retention/*`	Policy, archive, erasure requests
Sandbox	`/sandbox/*`	Provision evaluation workspace, status check
Monitoring	`/monitoring/`, `/health/`, `/metrics`	Workspace metrics, liveness, readiness, Prometheus

Key API Examples

Common governance workflows expressed as single API calls.

bash

Run compliance evaluation (7 frameworks)

1curl -X POST https://sovereign.yourcompany.com/api/v1/regulatory/evaluate \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model_id": "mdl_fraud_v4",
6    "frameworks": ["eu_ai_act", "sr_11_7", "nist_ai_rmf", "dora", "mas_trmg", "hipaa_fda", "sox_sec"],
7    "workspace_id": "ws-prod"
8  }'
9# → { "eval_id": "eval_abc123", "status": "running" }

bash

Trigger bias evaluation (DIR + SPD)

1curl -X POST https://sovereign.yourcompany.com/api/v1/bias/evaluate \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model_id": "mdl_credit_v2",
6    "dataset_id": "ds_applicants_2026",
7    "protected_attributes": ["gender", "race", "age_group"],
8    "label_column": "approved"
9  }'
10# → { "dir": 0.94, "spd": -0.02, "status": "pass", "intersectional": {...} }

bash

Run adversarial robustness test

1curl -X POST https://sovereign.yourcompany.com/api/v1/robustness/evaluate \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model_id": "mdl_fraud_v4",
6    "attacks": ["fgsm", "pgd", "carlini_wagner", "deepfool", "square_attack"],
7    "epsilon": 0.1
8  }'
9# → { "score": 0.78, "attacks": { "fgsm": 0.82, "pgd": 0.74, ... } }

bash

Kill switch — remove model from all traffic

1# Remove from traffic in <2 seconds
2curl -X POST https://sovereign.yourcompany.com/api/v1/models/mdl_fraud_v4/kill \
3  -H "Authorization: Bearer $TOKEN" \
4  -H "Content-Type: application/json" \
5  -d '{ "reason": "Critical drift PSI=0.31", "workspace_id": "ws-prod" }'
6
7# Revert to previous champion
8curl -X POST https://sovereign.yourcompany.com/api/v1/models/mdl_fraud_v4/revert \
9  -H "Authorization: Bearer $TOKEN" \
10  -d '{ "target_version": "mdl_fraud_v3" }'

bash

MCP Server — list available governance tools

1# List all 31 governance tools available in Claude Code / Desktop
2curl https://sovereign.yourcompany.com/api/v1/mcp/tools \
3  -H "Authorization: Bearer $TOKEN"
4# → { "tools": ["evaluate_compliance", "run_bias_check", "trigger_kill_switch",
5#               "get_audit_chain", "verify_chain_integrity", "export_audit_csv",
6#               "register_model", "get_model_card", "check_drift", ... ] }

Webhooks

Subscribe to platform events and receive signed HTTP POST payloads. Signatures use HMAC-SHA256: X-AegisSovereign-Signature: sha256=. Verify with AegisSovereignClient.verifyWebhookSignature(). Events marked Agent also trigger an AI Governance Agent automatically — external subscribers still receive the event regardless.

Event	Fired when	Agent triggered
`model.promoted`	Model successfully promoted to production	—
`model.promotion_blocked`	Promotion blocked by failed regulatory evaluation	IncidentResponseAgent
`model.killed`	Kill switch activated — model removed from all traffic	IncidentResponseAgent
`compliance.eval.completed`	Regulatory evaluation finished with scores	CompliancePipelineAgent
`bias_eval.failed`	Disparate Impact Ratio violation detected (DIR < 0.8)	IncidentResponseAgent
`bias_eval.warning`	DIR in warning range (0.8–0.9)	RemediationSuggestionAgent
`robustness_eval.failed`	Adversarial robustness score below threshold	IncidentResponseAgent
`drift.detected`	PSI ≥ 0.10 — alert threshold crossed	IncidentResponseAgent
`drift.critical`	PSI ≥ 0.25 — auto-rollback triggered	IncidentResponseAgent
`gitops.bundle.synced`	OPA/Rego policy bundle applied from GitHub push	—
`audit.chain.verified`	Audit chain integrity check completed	—
`federation.round.completed`	Federated learning aggregation round finished	GovernanceReportingAgent
`llm.budget_alert`	Workspace LLM spend reaches alert threshold	—
`safety_violation.critical`	Safety policy engine hard-blocks a request (critical severity)	IncidentResponseAgent + HumanReviewRequest
`safety_drift.detected`	Safety drift monitor detects anomaly via IsolationForest	IncidentResponseAgent + HumanReviewRequest
`safety_slo.breached`	Safety SLO burn rate exceeds 14.4× (5% weekly budget/hr)	IncidentResponseAgent + HumanReviewRequest

Error Format

All errors return a consistent JSON envelope.

json

Error response

1{
2  "detail": "Model not found.",          // human-readable message
3  "code": "NOT_FOUND",                   // machine-readable code
4  "status": 404,
5  "request_id": "req-8a2b-c91d"         // include in support tickets
6}