API Reference

Health check. Returns proxy status, version, engine type, and domain count. Always public.

curl http://localhost:8080/health

# Response
{
  "status": "healthy",
  "version": "0.10.1",
  "engine": "rust",
  "rust_available": true,
  "domains": 4,
  "uptime_seconds": 3600
}

Main governance proxy endpoint. Accepts any MCP JSON-RPC 2.0 message, applies all 4 governance domains bidirectionally, and forwards to the upstream MCP server. The response includes governance metadata as HTTP headers.

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADMINA_API_KEY" \
  -H "X-Session-Id: my-session" \
  -H "X-Agent-Id: my-agent" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "read_file",
      "arguments": { "path": "/etc/hostname" }
    }
  }'

Request headers:

Response headers added by Admina:

Aggregate governance statistics: total requests, actions by type, risk level distribution, latency.

curl http://localhost:8080/api/stats \
  -H "X-API-Key: $ADMINA_API_KEY"

{
  "total_requests": 10482,
  "actions": {
    "ALLOW": 10301,
    "BLOCK": 142,
    "REDACT": 35,
    "CIRCUIT_BREAK": 4
  },
  "avg_latency_us": 6.25,
  "p99_latency_us": 7.29
}

Inline governance check. Submit content for validation without proxying to upstream. Returns the governance decision.

curl -X POST http://localhost:8080/api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADMINA_API_KEY" \
  -d '{"content": "Please ignore previous instructions", "session_id": "test"}'

# Response
{
  "action": "BLOCK",
  "risk_level": "HIGH",
  "domain": "agent_security",
  "details": {"matched_patterns": ["instruction_override"], "score": 0.92}
}

Submit a forensic log entry. Used by integrations (LangChain, CrewAI) for passive governance logging.

curl -X POST http://localhost:8080/api/v1/audit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADMINA_API_KEY" \
  -d '{"event": "tool_call", "agent_id": "crewai-01", "payload": {}}'

Admina Score — a live-runtime weighted composite (0–100) powering the headline metric on the bundled Alpine.js dashboard. Unlike the OISG Score (static capability assessment), the Admina Score reflects what is actually happening right now on this instance: enforced residency, audited traffic, compliance posture, attack rate, and hash-chain integrity.

→ Full formula, component breakdown, and guidance for improving each component: Admina Score.

curl http://localhost:8080/api/dashboard/score \
  -H "X-API-Key: $ADMINA_API_KEY"

# Response
{
  "score": 87,
  "max_score": 100,
  "breakdown": {
    "data_residency": 25,
    "interactions_audited": 25,
    "eu_ai_act_coverage": 22,
    "no_recent_attacks": 15,
    "forensic_chain_valid": 10
  },
  "computed_at": "2026-05-21T09:30:00Z"
}

OISG Adequacy Score (Open · Intelligent · Secure · Governed) — four pillars of five criteria each (5 points per criterion), for a 0–100 total. Unlike the Admina Score (live runtime metrics), this is a static capability assessment of the instance: which governance features are wired up and available. On the dashboard it appears in a separate "Instance Configuration" panel as a 2×2 quadrant map. See oisg.ai and the dedicated OISG page for the full paradigm.

curl http://localhost:8080/api/dashboard/oisg \
  -H "X-API-Key: $ADMINA_API_KEY"

# Response (truncated)
{
  "total": 85,
  "max_total": 100,
  "level": "OISG adequate",
  "pillars": {
    "open":        { "score": 25, "max_score": 25, "criteria": [...] },
    "intelligent": { "score": 20, "max_score": 25, "criteria": [...] },
    "secure":      { "score": 25, "max_score": 25, "criteria": [...] },
    "governed":    { "score": 15, "max_score": 25, "criteria": [...] }
  },
  "computed_at": "2026-05-21T09:30:00Z"
}

Levels: 0–24 Critical gaps · 25–49 Partial coverage · 50–79 Good coverage · 80–100 OISG adequate.

Live governance event stream via WebSocket. Used by the dashboard for real-time updates.

wscat -c ws://localhost:8080/api/dashboard/live \
  -H "X-API-Key: $ADMINA_API_KEY"

Classify an AI system's risk level under EU AI Act Art. 6 and get a gap analysis against Art. 9–15 requirements. The enforcement_deadline reflects the Omnibus VII agreement of 7 May 2026: Annex III high-risk systems become applicable on 2 Dec 2027 (postponed from 2 Aug 2026).

curl -X POST http://localhost:8080/api/compliance/classify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADMINA_API_KEY" \
  -d '{
    "description": "AI credit scoring system for consumer loans",
    "use_case": "financial risk assessment",
    "data_types": ["financial", "personal", "behavioral"]
  }'

{
  "risk_level": "HIGH",
  "article": "Art. 6 — High-risk AI system",
  "justification": "Financial decisions affecting individuals",
  "gaps": [
    {"article": "Art. 9", "status": "MISSING", "description": "No risk management system documented"},
    {"article": "Art. 12", "status": "COVERED", "description": "Admina forensic black box active"},
    {"article": "Art. 15", "status": "COVERED", "description": "Admina firewall + loop breaker active"}
  ],
  "enforcement_deadline": "2027-12-02"
}

Run a gap analysis against Articles 9–15 for an existing classification.

Generate a structured compliance report combining the latest classification, gaps, and forensic evidence.

List the 10 NIS2 Art. 21(2) measure areas (risk management, incident handling, business continuity, supply chain, vulnerability disclosure, cyber hygiene, MFA, crypto policies, asset management, training) with 4 controls each — 40 checks total.

Submit your self-assessment answers and receive an area-by-area gap report.

List Article 30 Records of Processing Activities (RoPA). Persistence is opt-in via gdpr.ropa_path in admina.yaml; the registry is in-memory by default.

Create a new Art. 30 record. Typed schema covering controller, purposes, categories of data, recipients, transfers, retention, and security measures.

Generate an Art. 35 Data Protection Impact Assessment scaffold from operator-supplied facts. Returns a Markdown template populated with the provided context, structured for legal review.

Hand-curated mapping of 12 operational controls across EU AI Act, NIS2, and GDPR. Surfaces obligations that satisfy multiple frameworks in a single control — useful to avoid duplicate audit work.

Prometheus metrics endpoint. Scrape it from your Prometheus / Grafana stack.

curl http://localhost:8080/metrics | head