GridView Reporting API

Standalone reporting API and UI served from the reporting server. Default timezone: Africa/Johannesburg.

Protected JSON routes require an admin API key or scoped service API key in X-API-Key or Authorization: Bearer <key> or the optional read-only browser cookie for dashboard GET routes.

Configured service API keys: report-reader (read), tariff-admin (read, tariff_admin_write).

UI /health /health/streams /api-info /frontend-version /openapi.json

Endpoint Summary

GET /health: service health and runtime metadata.
GET /health/streams: source freshness, rollup freshness, and source-to-rollup lag by meter.
GET /meters: list meters that currently have reporting rows in the local rollup store.
GET /tariff-admin?meter=...: tariff catalog, meter assignment state, charge config, and holiday overrides.
POST /tariff-admin/meter-state: save meter availability and use.
POST /tariff-admin/assignment: save a meter tariff assignment.
POST /tariff-admin/charge-config: save a meter fixed-charge configuration.
POST /tariff-admin/holiday-override: save a plan holiday override.
GET /usage/hourly?meter=...&start=...&end=...: hourly usage rows and summary totals.
GET /billing/summary?meter=...&start=...&end=...: billing summary totals for a meter and range.
GET /billing/invoice.pdf?meter=...&start=...&end=...: printable billing invoice PDF.
GET /api-info: compact discovery JSON for agents and client bootstrapping.
GET /frontend-version: no-store frontend build metadata for update-aware clients.
GET /openapi.json: full OpenAPI contract.

Example Calls

curl -H "X-API-Key: YOUR_KEY" "http://gridview.reverse-proxy.co.za/meters"

curl -H "X-API-Key: YOUR_KEY" "http://gridview.reverse-proxy.co.za/health/streams"

curl -H "X-API-Key: YOUR_KEY" "http://gridview.reverse-proxy.co.za/tariff-admin?meter=meter-subtropico-fridge"

curl -H "X-API-Key: YOUR_KEY" "http://gridview.reverse-proxy.co.za/usage/hourly?meter=meter-subtropico-fridge&start=2026-03-01T00:00:00%2B02:00&end=2026-04-01T00:00:00%2B02:00"

curl -H "X-API-Key: YOUR_KEY" "http://gridview.reverse-proxy.co.za/billing/summary?meter=meter-subtropico-fridge&start=2026-03-01T00:00:00%2B02:00&end=2026-04-01T00:00:00%2B02:00"

curl -H "X-API-Key: YOUR_KEY" "http://gridview.reverse-proxy.co.za/billing/invoice.pdf?meter=meter-subtropico-fridge&start=2026-03-01T00:00:00%2B02:00&end=2026-04-01T00:00:00%2B02:00&amount_mode=rands"

Field Notes

kwh_net: net energy for the hour bucket.
energy_rate_ex_vat: resolved ex VAT energy rate for the hour.
energy_charge_ex_vat: kwh_net * energy_rate_ex_vat for that bucket.
quality: rollup quality marker such as ok, partial, or reset_detected.