Energy Management API

Overview

Control site load, orchestrate charging with facility constraints, and retrieve energy KPIs for reporting and optimisation.

Endpoints for meters, tariffs, schedules, and constraints
Forecasts for demand and renewable generation
Event webhooks for peaks, anomalies, and demand response

Ingestion & Security

Ingest device readings over HTTP with device keys and optional HMAC body signatures. MQTT and WebSockets are available for streaming gateways and live dashboards.

Device auth header: X-Device-Key: <uuid>
Optional HMAC header: X-Signature: hex(sha256(body, secret))
POST /api/energy/energy-data and /api/energy/energy-data/bulk

curl -sS -X POST https://api.joulepoint.com/api/energy/energy-data/   -H 'X-Device-Key: <api-key>'   -H 'X-Signature: <hmac sha256 of raw body>'   -H 'Content-Type: application/json'   -d '{"total_power":3600.0,"total_energy":1500.0,"voltage_a":230.1,"timestamp":"2025-10-16T10:00:00Z"}'

Analytics & KPIs

Query live and historical analytics for meters, groups, and accounts. Export CSVs and fetch naive forecasts for planning.

GET /api/energy/analytics/live_trail
GET /api/energy/analytics/kpi and /matrix
GET /api/energy/analytics/export and /forecast

Power Quality & Protection

Configure sags/swells, THD, and imbalance thresholds and stream detected PQ events. Protection events include trips, earth leakage and breaker state.

POST /api/energy/pq/config
GET /api/energy/pq/events and /api/energy/protection/events

{
  "meter_id": 5,
  "sag_v_threshold": 0.9,
  "swell_v_threshold": 1.1,
  "thd_pct_threshold": 5.0,
  "imbalance_pct_threshold": 2.0
}

Automations & Webhooks

Define rules on events to trigger actions like webhooks, annotations, relay commands with approvals, and wallet topups. Deliveries are retried with backoff and protected by circuit breakers.

Events include data.ingested, pq.event, protection.event, alert.triggered
Actions: webhook, plugin_action, relay_command (approval), notify_email, annotate, wallet_topup
Endpoints: /api/automations/rules, /actions, /deliveries/metrics, dry-run support

{
  "name":"HighPower",
  "event_key":"data.ingested",
  "throttle_seconds":300,
  "dedupe_template":"meter:{meter_id}",
  "jsonlogic": { ">": [ {"var":["event.total_power",0]}, 5000 ] },
  "rule_actions":[{"action_id": 123 }]
}

MLOps & Forecasting

Create datasets, run external training jobs, manage models and assignments, and route inference results back into the event stream for anomaly detection.

POST /api/ml/datasets then /{id}/build
POST /api/ml/training-jobs then /{id}/run
POST /api/ml/assignments and /promotions

Billing & Wallets

Preview TOU costs and generate statements for accounts; manage prepaid wallets with low‑balance events and automated topups via rules.

POST /api/energy/billing/accounts/{id}/preview
POST /api/energy/billing/accounts/{id}/generate_statement
APIs: /api/energy/wallets and /wallet-transactions

Topology Graph

Fetch the site energy graph with nodes and edges for 3D visualisation, including live power and losses overlays.

GET /api/energy/topology/nodes/graph

Authentication

Authenticate with OAuth2 bearer tokens. Create scoped credentials under Integrations → API Access.

Full Reference

For endpoints, schemas, and examples, open the external Postman documentation (link below).