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.9.0",
  "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 React 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-04-27T09: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-04-27T09: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.

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": "2026-08-02"
}