API Reference

Health check. Always public and always served, whatever ADMINA_ENABLED_SURFACES says.

curl http://localhost:8080/health

# Response (filesystem forensic backend, Rust engine)
{
  "status": "healthy",
  "service": "admina-proxy",
  "version": "0.13.0",
  "mode": "enforce",
  "surfaces": ["gateway", "mcp", "integration", "compliance", "dashboard"],
  "ruleset_sha256": "<64 hex>",
  "forensic_writable": true,
  "forensic_chain": "ok",
  "engine": {
    "engine": "rust",
    "rust_available": true,
    "rust_version": "0.13.0",
    "selection": "auto",
    "active": "rust",
    "pii_active": "python",
    "firewall": "rust",
    "loop_breaker": "rust",
    "pii": "python"
  },
  "timestamp": "2026-10-05T09:30:00+00:00"
}

engine is a nested object, not a string. selection echoes ADMINA_ENGINE (default auto), active is the engine the selection resolves to and pii_active is resolved separately — under auto the PII path stays on Python for full recall even when Rust is available. Since v0.13.0 firewall, loop_breaker and pii name the engines of the components the proxy actually built: loop_breaker is null when no enabled surface needs one (only mcp and integration do), and pii can also be presidio or a plugin engine's name. They can differ from active — an admina.yaml that sets Python-only firewall keys under auto gives firewall: "python" with active: "rust".

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.

The pipeline scans and redacts every string of the request down to 32 levels of nesting (6 before v0.13.0, when deeper text went through unscanned). With the firewall or PII redaction on, a request holding text deeper than that is blocked in enforce mode — a would-be block in observe / dry-run — with checks.scan_depth = {"action": "BLOCK", "reason": "depth_limit_exceeded"} in its forensic record.

A pluggable governance guard that raises ValueError, RuntimeError, OSError or TypeError is skipped by default — recorded as an ERROR entry in the request-side checks (its error is the exception's class name), logged only on the response side. With ADMINA_GUARD_FAIL_MODE=closed the exception becomes a BLOCK instead, on both the request and the response side of this endpoint. See Configuration.

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:

There is no header to override the upstream. In single-upstream mode everything goes to UPSTREAM_MCP_URL. With multi-upstream routing configured, the target is selected either by path — POST /mcp/route/{server} — or, when no route prefix is given, by resolving the called tool name (params.name) against the routing table.

Response headers added by Admina:

Status codes:

Denied requests carry no X-Admina-* headers at all — they are signalled by status code and JSON-RPC error body instead, and the governance, 500, 502 and 503 payloads include event_id (the rate-limit 429s, the MAX_REQUEST_TOKENS 413 and the 400 do not), so correlation with the forensic log still works. The block reason is fixed, not derived from the cause (still so in v0.13.0): a guard block, a response-guard block, a scan_depth block and — since v0.12.0 — an egress refusal (destination off the allowlist, undeterminable, or quarantined) also report "injection_detected". The actual cause is in the forensic record's checks — for egress, checks.egress.reason and checks.egress.blocked. No proxied request ever reports REDACT here: PII redaction rewrites the body in place and the request is still forwarded as an ALLOW. (REDACT is a value of the /api/v1/validate REST contract and of the action label of admina_requests_total.)

Since v0.13.0 a request is counted, emitted as a governance.decision event and stored in ClickHouse once it has been answered, with the action of its response: a response blocked by a governance guard makes the request a BLOCK (domain response_guard). Requests refused before the pipeline runs (rate limit, MAX_REQUEST_TOKENS) are counted as BLOCK; a body that is not JSON is not counted.

Aggregate governance statistics, nested one block per subsystem: the proxy's own request counters, engine diagnostics, and the per-domain counters of the firewall, loop breaker, PII redactor, forensic black box and compliance engine. Part of the dashboard surface; the dashboard session cookie is accepted here.

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

{
  "proxy": {
    "requests_total": 10482,
    "requests_blocked": 146,
    "requests_allowed": 10336,
    "requests_redacted": 35,
    "coordination_confirmed": 0,
    "coordination_suspected": 2,
    "coordination_degraded": 0,
    "prescan_accepted": 0,
    "prescan_ruleset_mismatch": 0,
    "prescan_malformed": 0,
    "prescan_ignored": 0,
    "avg_latency_ms": 41.27,
    "started_at": "2026-10-05T09:30:00+00:00"
  },
  "engine": {
    "engine": "rust",
    "rust_available": true,
    "rust_version": "0.13.0",
    "selection": "auto",
    "active": "rust",
    "pii_active": "python",
    "firewall": "rust",
    "loop_breaker": "rust",
    "pii": "python"
  },
  "firewall": {
    "total_checked": 10482,
    "total_blocked": 142,
    "block_rate": 1.35,
    "detections_by_type": { "instruction_override": 96, "role_hijack": 46 },
    "engine": "rust"
  },
  "loop_breaker": { "active_sessions": 12, "total_blocked": 4, "engine": "rust" },
  "pii_redactor": {
    "total_redacted": 35,
    "redactions_by_type": { "EMAIL": 22, "IBAN": 13 },
    "spacy_available": true,
    "engine": "python"
  },
  "forensic_blackbox": {
    "record_count": 10482,
    "chain_head": "9f2c1a7b4e8d0c35...",
    "storage_available": true
  },
  "compliance": { "total_assessments": 3, "enforcement_deadline": "2027-12-02" },
  "routing": {}
}

Since v0.12.2 (gateway) and v0.13.0 (/api/v1/validate) the requests_* counters count every governed surface — /mcp, /v1/chat/completions and /api/v1/validate — so the dashboard score counts gateway blocks too. requests_blocked counts BLOCK and CIRCUIT_BREAK, requests_allowed counts ALLOW and REDACT; a request that failed in the proxy before its decision (ERROR) counts only in requests_total. avg_latency_ms is a running average, in milliseconds rounded to 2 decimals, of the request duration from arrival to the end of the response — since v0.13.0 that includes the upstream's time, so it is no longer the governance overhead alone; there is no percentile series on this endpoint (see the histograms under /metrics). The three coordination_* counters (v0.12.0) count the coordination detector's verdicts, one key per recorded status (none and declared are not counted), and only /mcp feeds them. The four prescan_* counters (v0.13.0) count gateway requests by X-Admina-Scan-Policy outcome. loop_breaker is {} when no loop breaker is built (neither mcp nor integration enabled), forensic_blackbox is {} without a forensic store (the proxy normally has one, in-memory by default, where storage_available is false), and routing is {} unless multi-upstream routing is enabled.

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

Request body. A JSON object. content is required and must be a non-empty string: a missing or empty content returns HTTP 400 with detail 'content' field is required, and since v0.13.0 any other type returns HTTP 400 with 'content' must be a string (an object or array used to be scanned as nested data on the Python engine and answered 500 on the Rust engine). Optional: session_id (defaults to rest-<8 hex>), agent_id (defaults to rest-api), request_id (defaults to a uuid4 hex). All other keys are ignored. A non-object JSON body is rejected by FastAPI with HTTP 422.

Response body. Exactly five keys, always present: action, risk_level, checks, redacted_content, latency_ms. action is exactly one of the three values below — nothing else is reachable on this endpoint.

redacted_content is a string only when action is "REDACT"; it is null for ALLOW and BLOCK. Note the casing asymmetry: the top-level risk_level is uppercase (LOW / MEDIUM / HIGH / CRITICAL), while every risk_level nested inside checks is lowercase. latency_ms is a float rounded to 2 decimals. The checks keys are conditional, not fixed: loop_breaker is always present, firewall is present only when the loop breaker did not fire, pii_redaction is present only when the request is still allowed after the firewall stage, and egress (v0.12.0) is present when egress control is enabled for the integration surface and the request is still allowed after PII redaction. On this endpoint the egress stage reads the content string, so it finds a destination only when content begins with a URL or is an IP literal — under enforce such a request is refused unless the host is on the allowlist. See Egress control.

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 — injection detected
{
  "action": "BLOCK",
  "risk_level": "HIGH",
  "checks": { "loop_breaker": {...}, "firewall": { "is_injection": true, "risk_level": "high", ... } },
  "redacted_content": null,
  "latency_ms": 0.42
}

curl -X POST http://localhost:8080/api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADMINA_API_KEY" \
  -d '{"content": "Contact me at john.doe@example.com"}'

# Response — PII redacted (was "MODIFY" before v0.11.0)
{
  "action": "REDACT",
  "risk_level": "LOW",
  "checks": { "loop_breaker": {...}, "firewall": {...}, "pii_redaction": { "count": 1, "entities": [...] } },
  "redacted_content": "Contact me at [EMAIL]",
  "latency_ms": 1.13
}

This endpoint honours ADMINA_GOVERNANCE_MODE: in observe or dry-run mode a blocked request comes back as action: "ALLOW", but the mode downgrade does not suppress REDACT — a clean request carrying PII still returns REDACT with populated redacted_content. It always runs the firewall and PII redaction, whatever INJECTION_FAST_PATH_ENABLED and PII_REDACTION_ENABLED say, and runs no pluggable governance guards. A guard error in checks is returned as "Guard error", never the exception.

Since v0.13.0: a pipeline that raises is answered HTTP 500 ({"detail": "Internal Server Error"}, logged by exception class only); with ADMINA_FORENSIC_FAIL_MODE=closed the endpoint answers 503 while the forensic store does not accept records: its last write failed, the chain is invalid, or the configured backend could not be opened. Each request is counted on /metrics (surface integration), emits one governance.decision event (live feed, OpenTelemetry, one alert per block) and, with ClickHouse configured, stores one governance_events row of type validate_request. It writes no forensic record.

Submit a forensic log entry. Used by integrations (LangChain, CrewAI) for passive governance logging. Accepts the API key or, since v0.13.0, ADMINA_AUDIT_APPEND_KEY — a key that can append records here and do nothing else.

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

# Response
{
  "recorded": true,
  "sequence_number": 42,
  "record_hash": "28c61c2b1c389a2a...",
  "previous_hash": "1ef2510988f2ec99..."
}

When the record could not be written the response is "recorded": false with an error string (since v0.13.0, instead of reporting a record that was not stored), or HTTP 503 with ADMINA_FORENSIC_FAIL_MODE=closed. With the default configuration the built-in apikey auth provider admits API-key requests, so a record sent with the API key reads submitted_by: "user:api_key_user"; api_key appears only when no auth provider is loaded.

Reads the persisted forensic records back from the configured backend — one at a time, in sequence order, on a worker thread — and checks each record's hash, its link to the previous one, contiguous sequence numbers from 1 and, when a chain-state key is set, its signature. An invalid chain is a successful report — HTTP 200 with "valid": false — not a server error; only an unexpected exception produces a 500.

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

# Since v0.13.0: resume from the checkpoint of an earlier result
curl "http://localhost:8080/api/v1/forensic/verify?checkpoint=10482:<64-hex record_hash>" \
  -H "X-API-Key: $ADMINA_API_KEY"

# Response
{
  "valid": true,
  "records": 10482,
  "reason": null,
  "sequence_number": null,
  "checkpoint": { "sequence_number": 10482, "record_hash": "9f2c1a7b4e8d0c35..." },
  "signed": 10482,
  "unsigned": 0,
  "signatures_verified": true,
  "last_hash": "9f2c1a7b4e8d0c35...",
  "backend": "filesystem"
}

backend is one of memory, filesystem, s3. The in-memory store (the default) has no persisted chain: it reports "valid": true with "records": 0, whatever record_count says — verification needs FORENSIC_BACKEND=filesystem or s3. A configured backend that could not be opened at startup reports "valid": false, reason: "store_unavailable". A chain found invalid at startup never verifies. The record format, signatures and rebuild rules are on Domains; the CLI counterpart is admina forensic verify [--from-seq N | --checkpoint SEQ:HASH].

New in v0.12.1. Exchanges the API key — in X-API-Key or Authorization: Bearer; an existing session cannot mint a new one — for the admina_dashboard_session cookie: HttpOnly, SameSite=Strict, Path=/api/, signed with a key derived from ADMINA_API_KEY and valid for ADMINA_DASHBOARD_SESSION_TTL seconds (default 3600, 60 to 43200). It is Secure as DASHBOARD_COOKIE_SECURE says (auto since v0.13.0: over HTTPS, and over plain HTTP for any host that is not localhost, *.localhost or a loopback address). GET on the same path reports whether the caller is signed in; DELETE signs out. A live feed opened with a session is closed when the session expires. Sessions issued before v0.12.1 are not accepted.

curl -X POST http://localhost:8080/api/dashboard/session \
  -H "X-API-Key: $ADMINA_API_KEY" -c cookies.txt
# {"authenticated": true, "session": true, "expires_at": 1791266400}

Answers 404 when the dashboard is disabled (ADMINA_DASHBOARD_ENABLED=false) or the dashboard surface is off. Without ADMINA_API_KEY there is no key to exchange: the auth middleware answers 401, and the route's own 404 appears only once a request is admitted (ALLOW_UNAUTHENTICATED=true or another auth provider). Responses carry Cache-Control: no-store.

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: audited traffic, compliance posture, attack rate, and hash-chain integrity (plus a fixed residency credit for any running proxy).

→ 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": 12,
    "no_recent_attacks": 15,
    "forensic_chain_valid": 10
  },
  "computed_at": "2026-05-21T09:30:00+00:00"
}

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": 20, "max_score": 25, "criteria": [...] },
    "intelligent": { "score": 20, "max_score": 25, "criteria": [...] },
    "secure":      { "score": 25, "max_score": 25, "criteria": [...] },
    "governed":    { "score": 20, "max_score": 25, "criteria": [...] }
  },
  "computed_at": "2026-05-21T09:30:00+00:00"
}

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

Live governance event stream via WebSocket, fed by the event bus. Used by the dashboard for real-time updates. Since v0.12.2 / v0.13.0 it carries the governance.decision events of every governed surface — /mcp, the gateway and /api/v1/validate — whose metadata holds names, counts and hashes, never request text. Accepts the API key header, the dashboard session cookie or the deprecated ?api_key= parameter; a connection from an origin outside CORS_ORIGINS is closed (code 1008).

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

Classify an AI system's risk level under the EU AI Act risk taxonomy. Classification is keyword-driven over description, use_case and data_types, and returns one of four categories — unacceptable, high, limited, minimal — together with the static profile of that category. Since v0.13.0 it also matches Italian, French and German phrases (Art. 5 practices, Annex III areas, Art. 50 cases), so a non-English description can now get a higher class than before; English results are unchanged. The gap analysis against Art. 9–15 is a separate endpoint, POST /api/compliance/gap-analysis (below).

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_category": "high",
  "level": 3,
  "description": "High-risk AI systems requiring conformity assessment",
  "examples": [
    "credit scoring",
    "recruitment",
    "law enforcement",
    "critical infrastructure",
    "healthcare diagnostics"
  ],
  "action": "Requires conformity assessment, logging, human oversight",
  "matched_terms": [
    { "lang": "en", "risk": "high", "area": "keywords", "term": "credit scor" },
    { "lang": "en", "risk": "high", "area": "keywords", "term": "financial" }
  ],
  "matched_areas": ["keywords"]
}

level is an ordinal: 4 unacceptable, 3 high, 2 limited, 1 minimal. examples and action are the static profile of the matched category, not an analysis of the submitted system. matched_terms and matched_areas (new in v0.13.0) say which terms decided the class — an Italian CV-screening description, for instance, matches area: "employment". No gaps, article, justification or enforcement_deadline field is returned here. The Annex III enforcement deadline (2027-12-02, postponed from 2 Aug 2026 by the Omnibus VII agreement of 7 May 2026) is exposed by the compliance block of /api/stats.

Run a gap analysis against the Art. 9–15 requirements. Body: risk_category (default high) and current_compliance, a map of requirement key to a list of booleans, one per check. Returns compliance_score, total_checks, passed_checks, gaps, gap_count, status, enforcement_deadline and assessed_at. For a limited or minimal category it short-circuits to "applicable": false with a message. This is the call that feeds the eu_ai_act_coverage component of the Admina Score. POST only — a GET answers 405.

Generate a structured EU AI Act report for one submitted system. The body carries the system's own facts — system_name, description, use_case, data_types and current_compliance — and the call runs classification and gap analysis in a single shot, returning the combined report. Nothing is read from stored state, but the gap analysis it runs internally is recorded — it becomes the latest EU AI Act assessment seen by the GET report below and by the Admina Score.

Same path, different report: a consolidated snapshot of the running instance, with no body. It aggregates the latest EU AI Act assessment, the latest NIS2 assessment, the GDPR RoPA stats and records, the cross-regulation matrix, the proxy's runtime metrics and the forensic black box stats. Serialisation is selected with ?format=json (default), csv or markdown.

List the 10 NIS2 Art. 21(2) measure areas with 4 controls each — 40 checks total: policies on risk analysis and information system security; incident handling; business continuity (backup, disaster recovery, crisis management); supply chain security; security in network and IS acquisition, development, and maintenance; policies and procedures to assess effectiveness of measures; basic cyber hygiene practices and cybersecurity training; policies and procedures regarding the use of cryptography; human resources security, access control policies, asset management; multi-factor authentication and secure communications.

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

List Article 30 Records of Processing Activities (RoPA). The registry is in-memory by default; persistence is opt-in through the ADMINA_GDPR_ROPA_PATH environment variable (or an explicit storage_path= when constructing the registry in-process). Note that the commented gdpr.ropa_path key in admina.yaml.example is inert — the config loader has no gdpr section and the proxy builds the registry with no arguments, so only the environment variable takes effect.

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.

Runs the governance pipeline inline before forwarding — injection firewall, PII redaction, egress control (since v0.12.0) and pluggable governance guards. Loop detection does not run on this surface. Since v0.13.0 the pipeline runs in worker threads, off the event loop (ADMINA_GATEWAY_PIPELINE_WORKERS, default one per CPU), so a governance guard must be thread-safe.

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADMINA_API_KEY" \
  -d '{
    "model": "llama3.1:8b",
    "messages": [{"role": "user", "content": "Summarise this clause…"}]
  }'

Refused before governance. These are answered before any governance check, forensic record or upstream call, and are not counted on /metrics; they carry X-Admina-Ruleset and X-Admina-Version but no outcome headers. Bodies are in the OpenAI error format ({"error": {"message", "type", "param", "code"}}) unless noted.

What is scanned. Since v0.13.0 the firewall scans every string of the request body, keys included: the messages (content, names, tool calls), the tool definitions (tools), response_format and any other field. Tool call arguments are scanned as the JSON they hold, each string separately. With the firewall on, a string nested more than 32 levels deep blocks the request in enforce mode, with checks.scan_depth in its record. ADMINA_GATEWAY_SCAN_ROLES (default system,user,assistant,tool; other roles are always scanned) and, when ADMINA_GATEWAY_SCAN_POLICY_ENABLED=true, the request header X-Admina-Scan-Policy narrow the messages only. PII redaction rewrites the text of each message — content (a string or the text of each part), reasoning and refusal text, tool call arguments — and keeps roles, names, tool call ids, image and audio parts as received.

The egress stage reads the text of the chat messages, history included, so it sees a destination in any message that begins with a URL and in every multimodal image_url part. Under ADMINA_EGRESS_MODE=enforce that has two practical effects: a vision request whose image host is not on the allowlist is refused — and an inline base64 (data:) image always is, since it has no host to allowlist — and once a message beginning with an unlisted URL is in the history, every later turn of that conversation is refused too. Since v0.13.0 agent_security.egress.surfaces can leave the gateway out of egress control. The coordination detector is not fed from this surface. See Egress control.

Optional request headers:

What is forwarded. The body as received, with messages replaced by the PII-redacted version when PII was found. Since v0.13.0, three settings (all off by default) narrow it: ADMINA_GATEWAY_FORWARD_FIELDS (the top-level fields forwarded; model, messages and stream always are), ADMINA_GATEWAY_MAX_N and ADMINA_GATEWAY_MAX_COMPLETION_TOKENS (larger values are lowered; a request with neither token field gets max_tokens set to the limit). They never change the messages or what the firewall scans.

Allowed responses. Upstream errors (4xx, 5xx) reach the client with their status, body and content type, streaming or not (since v0.13.0). A successful non-streaming response is returned as received while PII redaction is off; with PII redaction on (the default) its JSON is parsed and every string redacted as a whole value, keeping structural values (index, id, type, role, name, finish_reason) and sending logprobs / token_ids as null; a success body that is not a JSON object then gets 502 (code upstream_invalid_response). No wrapper object and no Admina fields are added to the body.

With "stream": true the reply is text/event-stream, relayed by ADMINA_GATEWAY_STREAM_MODE (or gateway.stream_mode):

Before v0.13.0 only choices[0].delta.content was re-emitted, so n > 1, tool-call deltas and usage chunks were lost and a streamed reply was always HTTP 200; neither is true any more. A completion whose PII redaction does not finish (over ADMINA_GATEWAY_PIPELINE_TIMEOUT, or raising) is not sent: a non-streaming one is answered as a block, a stream ends with one data: {"error": ...} event (code response_redaction_failed) and no data: [DONE].

Response headers (since v0.13.0):

# Response on BLOCK — HTTP 200 (default ADMINA_GATEWAY_BLOCK_STATUS)
# X-Admina-Action: BLOCK   X-Admina-Risk: CRITICAL   X-Admina-Categories: instruction_override,prompt_extraction
{
  "id": "chatcmpl-admina-1a2b3c4d5e6f",
  "object": "chat.completion",
  "created": 1784200000,
  "model": "llama3.1:8b",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "This request was blocked by the Admina governance policy."},
    "finish_reason": "content_filter"
  }],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
}

Blocked in every governance mode, recorded under checks.pipeline: a pipeline that raises (since v0.13.0; it was a 500), one that exceeds ADMINA_GATEWAY_PIPELINE_TIMEOUT seconds (default 0, no limit; the wait for a worker thread counts), and a PII redaction that masked text but returned no messages. Guard contract errors still follow ADMINA_GUARD_FAIL_MODE.

Failures answered by the gateway (OpenAI error format, never exception text; since v0.13.0):

Forensic records. Since v0.13.0 each chat completion writes two records with the same event_id — count gateway_request records to count requests. Neither contains prompt text, response text or the model name.

Proxies the model list of the selected route (X-Admina-Upstream), sending the route's key. Without an allow-list the upstream body and status are returned as-is. This route is a passthrough: it is not governed, not counted and not written to the forensic log. Timeouts and transport failures get the same 504 / 502 bodies as chat completions.

ADMINA_GATEWAY_MODELS_ALLOWLIST (comma-separated, empty by default) filters the returned data[] by model id. Since v0.13.0 the same list is also enforced on POST /v1/chat/completions (403 model_not_allowed, above) — it is an access-control policy, not just a listing filter.

curl http://localhost:8080/v1/models \
  -H "X-API-Key: $ADMINA_API_KEY"

New in v0.13.0. The active firewall ruleset: ruleset_sha256 is the SHA-256 of the RFC 8785 canonical JSON in ruleset_document — ruleset_format, admina_version, engine, builtin patterns (or the admina-core version on Rust), pattern packs, custom patterns, disabled categories and patterns, allowed tags, heuristic threshold — the value carried by X-Admina-Ruleset and /health. Use it to pin gateway.prescan_rulesets and X-Admina-Scan-Policy. Because the hashed object includes admina_version (and admina_core_version on Rust), the hash changes with every upgrade, not only when the rules change: recompute pinned hashes after each one.

curl http://localhost:8080/v1/admina/ruleset \
  -H "X-API-Key: $ADMINA_API_KEY"

# Response (ruleset_document truncated)
{
  "ruleset_sha256": "<64 hex>",
  "ruleset_format": 1,
  "ruleset_document": "{\"admina_version\":\"0.13.0\",\"allowed_tags\":[],...}",
  "engine": "rust",
  "admina_core_version": "0.13.0",
  "admina_version": "0.13.0",
  "accepted_prescan_rulesets": ["<64 hex>"],
  "prescan_tags": [],
  "scan_roles": ["system", "user", "assistant", "tool"],
  "scan_policy_enabled": false
}

Prometheus metrics endpoint. Scrape it from your Prometheus / Grafana stack. Public unless ADMINA_METRICS_REQUIRE_AUTH=true (since v0.13.0); always served, whatever ADMINA_ENABLED_SURFACES says.

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

The exposition is generated inline (no prometheus_client dependency). Label values come from fixed sets only, never from a request. Families:

# Since v0.13.0 — one sample per surface and action
# HELP admina_requests_total Governed requests per surface and action
# TYPE admina_requests_total counter
admina_requests_total{surface="gateway",action="ALLOW"} 9120
admina_requests_total{surface="gateway",action="BLOCK"} 41
admina_requests_total{surface="gateway",action="REDACT"} 35
...
admina_requests_total{surface="mcp",action="BLOCK"} 105
...
admina_engine_info{engine="rust",firewall="rust",loop_breaker="rust",pii="python",pii_redaction="on",rust_available="yes",rust_version="0.13.0",selection="auto",version="0.13.0"} 1

Upgrading from v0.12: dashboards and alerts that select on the unlabelled admina_requests_total or on the old admina_engine_info labels need updating — wrap the counter in sum() to keep the old meaning (plus /api/v1/validate traffic, and gateway traffic if you come from v0.12.1 or earlier). Fixed in v0.12.0: # HELP and # TYPE are emitted once per metric family; earlier releases repeated them per sample, so a proxy with detections in two or more firewall categories served an exposition Prometheus rejects, failing the whole scrape until restart.