Compliance Endpoints

Compliance dashboard, matrix, charts, and assessment endpoints — the domain-neutral platform dashboard, served by the orchestration engine and proxied through the API gateway under /api/v1/compliance/*. (The legacy deadline/production/risk endpoints on the RRC-specific compliance-monitor service also live under /api/v1/compliance/* — see Compliance Monitor.)

Endpoints

GET /api/v1/compliance/summary

High-level compliance summary metrics. Each count is a distinct-entity count (COUNT(DISTINCT entity_id)) over the same selector the matrix uses for the matching bucket, so a tile’s number always reconciles with the matrix total when that tile is clicked. The four buckets are overdue, due_7d, due_30d, and anomalies (anomalies keys on an explicit details.anomaly flag, not a text-substring match — R41 A7).

The *_delta fields are real week-over-week deltas (R41 A7): today’s live count minus the most recent compliance_daily_snapshot rollup at least a week old. Until a week of history has accrued the delta is 0 (the UI hides the chip) — an honest “no trend yet”, not a fabricated number.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/compliance/summary

Response (200):

{
  "overdue_count": 3,
  "overdue_delta": 1,
  "due_7_days_count": 5,
  "due_7_days_delta": 0,
  "due_30_days_count": 12,
  "due_30_days_delta": 0,
  "anomaly_count": 2,
  "anomaly_delta": 0
}

GET /api/v1/compliance/matrix

Entity x compliance domain matrix with color-coded status.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/compliance/matrix?entity_type=Well&status=red&limit=50&offset=0"

status (toolbar) and bucket (tile) are independent and may be combined; the matrix applies both with AND. bucket selects entities that have at least one domain row matching the bucket, then returns all of that entity’s domain cells.

Response (200):

{
  "rows": [
    {
      "entity_id": "well-001",
      "entity_name": "Smith Ranch #1",
      "entity_type": "Well",
      "domains": {
        "spacing": "green",
        "flaring": "amber",
        "production": "green",
        "permits": "green"
      }
    }
  ],
  "total": 28,
  "limit": 50,
  "offset": 0
}

Status codes: green = compliant, amber = attention needed, red = violation, grey = unknown/not assessed, blue = in progress.

GET /api/v1/compliance/domains

Installed compliance domains, served from the discovered pack manifests. The frontend derives the matrix columns and chart series from this list, so installing or removing a pack changes the UI with zero frontend edits.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/compliance/domains

[
  {"domain": "epa_oooob", "title": "EPA OOOOb Methane Compliance", "short_title": "OOOOb"},
  {"domain": "rule_37", "title": "Rule 37 Spacing Exception", "short_title": "Rule 37"}
]

short_title is the pack manifest’s compact label for dense surfaces (column headers, legends); it falls back to title when a manifest omits it.

GET /api/v1/compliance/charts/deadlines

Deadline bar chart data grouped by timeframe.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/compliance/charts/deadlines

GET /api/v1/compliance/charts/trend

Compliance-percentage trend over time. Reads the recorded compliance_daily_snapshot history (R41 A7) — a real multi-point series once history has accrued. Before any history exists it returns a single honest current point (never a synthetic series).

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/compliance/charts/trend?days=90"

GET /api/v1/compliance/charts/filings

Filing status distribution (donut chart data).

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/compliance/charts/filings

GET /api/v1/compliance/charts/flaring

Flaring volume chart data across the portfolio.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/compliance/charts/flaring

POST /api/v1/compliance/assess

Trigger a compliance assessment for the entire portfolio. Also records the day’s compliance_daily_snapshot rollup (backing deltas/trend). If every domain query fails (knowledge graph unreachable) the endpoint returns 503 rather than a misleading “0 statuses” success; a partial failure returns status: "partial" with a failed_domains map (R41 A5) — a graph outage never reads as “all compliant”.

curl -X POST http://localhost:8000/api/v1/compliance/assess \
  -H "Authorization: Bearer $TOKEN"

POST /api/v1/compliance/assess/{entity_id}

Trigger a compliance assessment for a single entity.

curl -X POST http://localhost:8000/api/v1/compliance/assess/well-001 \
  -H "Authorization: Bearer $TOKEN"