Governance dashboard API

The governance dashboard API returns a single, tenant-scoped inventory of a tenant's AI-governance posture, aggregating surfaces that already exist as separate mechanisms into one payload:

Guardrail activity and data residency — the same mechanical counts the compliance report exports, over a time window.
EU-AI-Act template state — how many governance templates are configured and how many are DPO-authoritative.
Compliance-report history — the tenant's stored monthly compliance-report snapshots, downloadable as CSV or PDF.
Agent-approval workflow status — the count of pending agent-egress approvals awaiting a decision.

It reads only; it stores, caches, and computes nothing of its own. The metric definitions are not restated here — they are owned by the compliance report API.

Base URL: https://<your-gateway-host>/admin/v1

GET /governance/dashboard

Returns the aggregated dashboard for one tenant as JSON.

Required role: admin, tenant_admin, or ki_manager.

curl 'https://<your-gateway-host>/admin/v1/governance/dashboard?tenant_id=<id>'

Tenant scope

Tenant scope is decided server-side; the client value never widens it. The dashboard is inherently per-tenant — there is no global/all-tenant variant.

Caller	Scope
`admin`	Must target one tenant with `?tenant_id=<id>`.
`tenant_admin` / `ki_manager`	Always their own tenant. A `?tenant_id` naming another tenant is ignored (pinned to the caller's own).

An admin who omits ?tenant_id is rejected 400 { "error": "tenant_id required" } (no query runs). A non-admin whose account carries no tenant is refused 403 { "error": "forbidden" }.

Approval-count visibility. The pending-approval count is surfaced to any of the three roles above. Actioning an approval — and the approval inbox itself, which reveals the held egress — remains restricted to a tenant admin (the admin or tenant_admin role) and is scoped to the caller's own tenant (see scheduled tasks / approvals). The count is a tenant aggregate carrying no recipient or content, so a ki_manager sees the number without gaining access to the inbox.

Query parameters

Parameter	Accepted	Rejected
`tenant_id`	A single tenant id string (`admin` only; ignored for other roles).	A repeated (`?tenant_id=a&tenant_id=b`) or valueless (`?tenant_id`) parameter → `400 { "error": "tenant_id must be a single value" }`.
`from`, `to`	A pair of finite unix-second integers with `from < to`. Both must be present to take effect.	A present non-numeric or non-finite bound, or `from >= to` → `400`. A lone `from` or `to` (not both) is ignored and the default window applies.

The window applies to metrics only. templates, compliance_reports, and approvals are point-in-time current state, unaffected by from/to. Default window: the last 30 days; maximum: clamped to 366 days, identical to the compliance report.

Bad input is rejected at the boundary before any database work. A storage failure on any of the four aggregated reads returns 500 { "error": "..." } — never a partial or misleading inventory (fail-closed).

Response

200 OK, Content-Type: application/json.

{
  "window": { "from_ms": 1767225600000, "to_ms": 1769904000000 },
  "metrics": {
    "requests_total": 48213,
    "requests_redacted": 192,
    "requests_detector_hit": 204,
    "requests_blocked": 57,
    "blocked_rate_limit": 4,
    "blocked_budget_quota": 2,
    "blocked_pii_gate": 9,
    "blocked_ip_allowlist": 1,
    "blocked_plan_model": 3,
    "blocked_guardrail": 38,
    "auth_failures": 11,
    "residency_eu": 47010,
    "residency_non_eu": 20,
    "residency_unknown": 6,
    "residency_no_dispatch": 120
  },
  "residency_authoritative": false,
  "templates": { "total": 3, "authoritative": 0 },
  "compliance_reports": {
    "total": 2,
    "reports": [
      { "id": "…", "period_from_ms": 1767225600000, "period_to_ms": 1769904000000, "generated_at_ms": 1770000000000 }
    ]
  },
  "approvals": { "pending": 4 }
}

Field	Meaning
`window`	The `[from_ms, to_ms)` window (unix ms) the `metrics` cover.
`metrics`	The complete compliance metric map for the window — see the metric definitions. Always fully populated (zero-defaulted).
`residency_authoritative`	`true` only when the residency breakdown is authoritative evidence (no unresolved zones and the whole period post-dates residency-recording go-live); otherwise the four `residency_*` counts are an approximation. Same verdict as the compliance report's `residency_basis`.
`templates.total`	Live governance templates configured for the tenant.
`templates.authoritative`	How many are DPO-signed authoritative mappings. `0` until a DPO signs (the data model carries the flag; UI-created templates are always non-authoritative).
`compliance_reports.total`	Number of stored monthly snapshots.
`compliance_reports.reports`	Metadata for each stored snapshot, newest period first (a JSON array — `[]` when none). Download a snapshot via `GET /compliance/reports/{id}`.
`approvals.pending`	Exact count of pending agent-egress approvals awaiting a decision.

Scope

This endpoint ships the tenant-aggregate inventory. A future per-entity inventory (models, agents, connectors, workflows with their individual approval state and guardrail-hit counts) converges onto this same surface; it is intentionally not a second, competing view.