Compliance Endpoints

Compliance dashboard, matrix, charts, and assessment endpoints. Served through the API gateway at http://localhost:8000.

Endpoints

Method	Path	Description
`GET`	`/compliance/summary`	Compliance summary cards
`GET`	`/compliance/matrix`	Entity x domain compliance matrix
`GET`	`/compliance/charts/deadlines`	Upcoming deadline chart data
`GET`	`/compliance/charts/trend`	Compliance trend over time
`GET`	`/compliance/charts/filings`	Filing status distribution
`GET`	`/compliance/charts/flaring`	Flaring volume chart data
`POST`	`/compliance/assess`	Trigger full portfolio assessment
`POST`	`/compliance/assess/{entity_id}`	Assess a single entity

GET /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.


curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/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 /compliance/matrix

Entity x compliance domain matrix with color-coded status.


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

Parameter	Type	Description
`entity_type`	string	Filter: `Well`, `Lease`, `Field`, `Facility`, etc.
`status`	string	Toolbar status filter: `overdue`, `action_needed`, `compliant`, `in_review`
`bucket`	string	Summary-tile filter: `overdue`, `due_7d`, `due_30d`, `anomalies`. Shares its selector with `/compliance/summary`, so the matrix `total` equals the count on the clicked tile. Unknown values return `422`.
`search`	string	Search entity name or identifier
`sort_by`	string	Sort field
`page`	int	Page number (default 1)
`page_size`	int	Page size (default 50, max 200)

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 /compliance/charts/deadlines

Deadline bar chart data grouped by timeframe.


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

GET /compliance/charts/trend

Compliance trend data over time.


curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/compliance/charts/trend?period=30d"

GET /compliance/charts/filings

Filing status distribution (donut chart data).


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

GET /compliance/charts/flaring

Flaring volume chart data across the portfolio.


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

POST /compliance/assess

Trigger a compliance assessment for the entire portfolio.


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

POST /compliance/assess/{entity_id}

Trigger a compliance assessment for a single entity.


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