API reference

Base URL https://api.owner.dynvolt.com — all paths below are relative to it. Generated from the OpenAPI spec (v1.0.0).

Sites

Endpoint	Summary
`GET /v1/sites`	List the sites this API key can access

Plant

Endpoint	Summary
`GET /v1/sites/{site_id}/overview`	Full live plant snapshot (loggers, inverters, strings, sensors, weather, predictions)
`GET /v1/sites/{site_id}/plant/status`	Aggregated live plant status
`GET /v1/sites/{site_id}/plant/summary`	Per-logger daily energy summary (?date=YYYY-MM-DD)
`GET /v1/sites/{site_id}/locations`	Site locations
`GET /v1/sites/{site_id}/locations/{location_id}`	One location
`GET /v1/sites/{site_id}/gaps`	Telemetry gap records (?logger_id&start&end)
`GET /v1/sites/{site_id}/gaps/logger/{logger_id}`	Telemetry gaps for one logger

Loggers

Endpoint	Summary
`GET /v1/sites/{site_id}/loggers`	List SmartLoggers (plants)
`GET /v1/sites/{site_id}/loggers/{logger_id}/history`	Logger telemetry history (?start&end&limit)

Inverters

Endpoint	Summary
`GET /v1/sites/{site_id}/inverters`	List inverters (?logger_id= to filter)
`GET /v1/sites/{site_id}/inverters/{inverter_id}`	One inverter with live telemetry
`GET /v1/sites/{site_id}/inverters/{inverter_id}/history`	Inverter telemetry history (?start&end&limit)
`GET /v1/sites/{site_id}/inverters/alarms/table`	Manufacturer alarm reference table
`GET /v1/sites/{site_id}/inverters/alarms/decode`	Decode alarm bitmasks (?alarm_1..alarm_5)

Strings

Endpoint	Summary
`GET /v1/sites/{site_id}/strings/inverter/{inverter_id}`	PV-string configuration for an inverter
`GET /v1/sites/{site_id}/strings/inverter/{inverter_id}/current`	Live per-string telemetry
`GET /v1/sites/{site_id}/strings/inverter/{inverter_id}/history`	Per-string history (?start&end&string_index&limit)
`GET /v1/sites/{site_id}/strings/inverter/{inverter_id}/hourly`	Per-string hourly energy (?start&end)

Sensors

Endpoint	Summary
`GET /v1/sites/{site_id}/sensors`	Transformer-station sensor/fan nodes
`GET /v1/sites/{site_id}/sensors/{node_id}/current`	Live sensor-node reading (temp/humidity/fan currents)
`GET /v1/sites/{site_id}/sensors/{node_id}/history`	Sensor-node history (?start&end&limit)

Weather

Endpoint	Summary
`GET /v1/sites/{site_id}/weather`	Latest on-site weather across all loggers (per-instrument under sensors[])
`GET /v1/sites/{site_id}/weather/logger/{logger_id}`	Latest weather for one logger (plot average + per-instrument)
`GET /v1/sites/{site_id}/weather/logger/{logger_id}/history`	Weather history 5-min buckets (?start&end&limit)

Efficiency & diagnostics

Endpoint	Summary
`GET /v1/sites/{site_id}/efficiency/loggers`	Logger specific-yield / capacity-factor rankings (?start&end)
`GET /v1/sites/{site_id}/efficiency/inverters`	Inverter rankings incl. efficiency (?start&end&logger_id)
`GET /v1/sites/{site_id}/efficiency/strings`	String rankings by orientation group (?start&end&inverter_ids&orientation)
`GET /v1/sites/{site_id}/efficiency/health-matrix`	Per-string health grid vs peers (?start&end)
`GET /v1/sites/{site_id}/efficiency/loss-analysis`	DC→AC conversion loss per inverter (?start&end)
`GET /v1/sites/{site_id}/strings/inverter/{inverter_id}/compare`	All strings of an inverter side-by-side (?start&end)

I-V curves

Endpoint	Summary
`GET /v1/sites/{site_id}/iv/modules`	Panel-model library
`GET /v1/sites/{site_id}/iv/modules/search`	Search the CEC panel database (?q&limit)
`GET /v1/sites/{site_id}/iv/modules/{params_id}`	One panel model
`GET /v1/sites/{site_id}/iv/strings/{inverter_id}/{string_index}/expected`	Expected-vs-measured I-V series for a string (?start&end&limit)

Energy

Endpoint	Summary
`GET /v1/sites/{site_id}/energy/hourly`	Day-by-hour energy matrix (?start&end&logger_ids)
`GET /v1/sites/{site_id}/loggers/{logger_id}/hourly-energy`	Hourly production for one logger (?since=UTC ISO)

Curtailment

Endpoint	Summary
`GET /v1/sites/{site_id}/curtailment`	Active + scheduled curtailment windows (rows carry group_id, applied, is_active)
`GET /v1/sites/{site_id}/curtailment/suggest`	Suggest a power limit from forecast (?logger_id&date&start_hour&end_hour)
`GET /v1/sites/{site_id}/commands/relay-history`	Relay/fan command history (?node_id&limit)
`POST /v1/sites/{site_id}/curtailment/window`	Schedule a curtailment window (site or single plant)
`POST /v1/sites/{site_id}/curtailment/immediate`	Curtail now (applied within ~10s)
`DELETE /v1/sites/{site_id}/curtailment/group/{group_id}`	Release a curtailment group (restores clamped power first)

Markets

Endpoint	Summary
`GET /v1/sites/{site_id}/markets`	Available markets
`GET /v1/sites/{site_id}/markets/{market_code}/prices`	Day-ahead prices for a market (?target_date)
`GET /v1/sites/{site_id}/markets/compare`	Cross-market price comparison (?target_date)

Earnings

Endpoint	Summary
`GET /v1/sites/{site_id}/earnings/summary`	Earnings summary gross→fees→net (?start&end&logger_id)
`GET /v1/sites/{site_id}/earnings/hourly`	Hourly earnings detail (?start&end&logger_id)
`GET /v1/sites/{site_id}/earnings/market-assignments`	Per-plant market assignment (?logger_id)
`GET /v1/sites/{site_id}/earnings/cross-border-prices`	Cross-border price series (?base&sold&start&end)

Predictions

Endpoint	Summary
`GET /v1/sites/{site_id}/predictions/forecast`	Production forecast, all plants (?date&refresh)
`GET /v1/sites/{site_id}/predictions/forecast/logger/{logger_id}`	Production forecast for one plant (?date)
`GET /v1/sites/{site_id}/predictions/production`	Forecast vs actual production (?start&end&logger_id)
`GET /v1/sites/{site_id}/predictions/prices`	Price forecast for the assigned market (?start&end)
`GET /v1/sites/{site_id}/predictions/model-status`	Model accuracy metrics

BESS

Endpoint	Summary
`GET /v1/sites/{site_id}/bess`	Battery-storage units
`GET /v1/sites/{site_id}/bess/fleet/summary`	BESS fleet aggregate
`GET /v1/sites/{site_id}/bess/{bess_id}`	One BESS unit
`GET /v1/sites/{site_id}/bess/{bess_id}/current`	Live BESS telemetry
`GET /v1/sites/{site_id}/bess/{bess_id}/history`	BESS telemetry history (?start&end&limit)
`GET /v1/sites/{site_id}/bess/{bess_id}/dashboard`	BESS unit dashboard (telemetry + schedule + deviations)
`GET /v1/sites/{site_id}/bess/{bess_id}/deviations`	Schedule-vs-actual deviations (?target_date)
`GET /v1/sites/{site_id}/bess/{bess_id}/clusters`	Per-cluster summaries
`GET /v1/sites/{site_id}/bess/{bess_id}/clusters/{cluster_idx}`	Live cluster cell arrays
`GET /v1/sites/{site_id}/bess/{bess_id}/pcs/current`	PCS live telemetry
`GET /v1/sites/{site_id}/bess/{bess_id}/pcs/history`	PCS history (?start&end&limit)
`GET /v1/sites/{site_id}/bess/{bess_id}/pcs/faults`	Live PCS fault words
`GET /v1/sites/{site_id}/bess/{bess_id}/alarms/states`	BESS alarm states (?only_set&severity)
`GET /v1/sites/{site_id}/bess/{bess_id}/alarms/history`	BESS alarm history (?code&limit)
`GET /v1/sites/{site_id}/bess/{bess_id}/alarms/counts`	Alarm counts by severity
`GET /v1/sites/{site_id}/bess/{bess_id}/dispatch-log`	Dispatch log (?start&end&limit)
`GET /v1/sites/{site_id}/bess/{bess_id}/control-log`	Control-write log (?tier&limit)
`GET /v1/sites/{site_id}/bess/{bess_id}/envelope`	Charge/discharge envelope + SOC
`GET /v1/sites/{site_id}/bess/{bess_id}/protection`	Protection thresholds
`GET /v1/sites/{site_id}/bess/{bess_id}/setup`	Device setup values
`GET /v1/sites/{site_id}/bess/{bess_id}/schedules`	Dispatch schedules for a unit (?target_date)
`GET /v1/sites/{site_id}/bess/schedules/{schedule_id}`	One dispatch schedule with hours
`POST /v1/sites/{site_id}/bess/{bess_id}/optimize`	Ask the AI to optimize this unit's dispatch
`POST /v1/sites/{site_id}/bess/optimize-all`	Optimize all units
`POST /v1/sites/{site_id}/bess/schedules/{schedule_id}/approve`	Approve a proposed dispatch schedule
`POST /v1/sites/{site_id}/bess/schedules/{schedule_id}/reject`	Reject a proposed dispatch schedule
`POST /v1/sites/{site_id}/bess/schedules/approve-all`	Approve all proposed schedules (?target_date)
`PUT /v1/sites/{site_id}/bess/schedules/{schedule_id}/hours/{hour}`	Edit one hour of a proposed schedule

Alerts

Endpoint	Summary
`GET /v1/sites/{site_id}/alerts`	Alerts (?status= repeatable; default active,acknowledged)
`POST /v1/sites/{site_id}/alerts/{alert_id}/acknowledge`	Acknowledge an alert
`POST /v1/sites/{site_id}/alerts/{alert_id}/resolve`	Resolve an alert

Work orders

Endpoint	Summary
`GET /v1/sites/{site_id}/work-orders`	O&M work orders (filters: location_id, logger_id, status, start, end, offset, limit)
`POST /v1/sites/{site_id}/work-orders`	Create a work order
`GET /v1/sites/{site_id}/work-orders/{wo_id}`	One work order
`PUT /v1/sites/{site_id}/work-orders/{wo_id}`	Update a work order
`GET /v1/sites/{site_id}/om/categories`	Inspection categories
`GET /v1/sites/{site_id}/om/notifications`	O&M notifications (?unread_only&offset&limit)
`GET /v1/sites/{site_id}/om/notifications/unread-count`	Unread O&M notification count
`PUT /v1/sites/{site_id}/work-orders/{wo_id}/items/{item_id}`	Update a work-order checklist item
`POST /v1/sites/{site_id}/work-orders/{wo_id}/approve`	Approve a completed work order
`PUT /v1/sites/{site_id}/om/notifications/{notification_id}/read`	Mark an O&M notification read

Defects

Endpoint	Summary
`GET /v1/sites/{site_id}/defects`	O&M defects (?location_id&logger_id&status&severity&offset&limit)
`POST /v1/sites/{site_id}/defects`	Log a defect
`GET /v1/sites/{site_id}/defects/{defect_id}`	One defect
`PUT /v1/sites/{site_id}/defects/{defect_id}`	Update a defect

Reports

Endpoint	Summary
`GET /v1/sites/{site_id}/reports/overview`	Reports overview
`GET /v1/sites/{site_id}/reports/catalog`	Report template catalog
`GET /v1/sites/{site_id}/reports/runs`	Generated report runs (?limit)
`GET /v1/sites/{site_id}/reports/subscriptions`	Scheduled report subscriptions
`POST /v1/sites/{site_id}/reports/subscriptions`	Create a report subscription
`DELETE /v1/sites/{site_id}/reports/subscriptions/{sub_id}`	Delete a report subscription
`PATCH /v1/sites/{site_id}/reports/subscriptions/{sub_id}`	Update a report subscription
`POST /v1/sites/{site_id}/reports/subscriptions/{sub_id}/run`	Run a report subscription now

The endpoints below are the only mutations in the API. They all accept the Idempotency-Key header and are rate-limited at 30 requests/min per token. Two areas are control writes that command the plant — curtailment (schedule / immediate / release) and BESS dispatch approval — and require the curtailment:write / bess:write scopes. Curtailment can only ever reduce output; no write can raise a plant above its grid-connection permit. Raw hardware control (BESS power/breaker/grid-mode, settings, panel-model edits) is not exposed by design.

POST /v1/sites/{site_id}/curtailment/window — Schedule a curtailment window (site or single plant)
POST /v1/sites/{site_id}/curtailment/immediate — Curtail now (applied within ~10s)
DELETE /v1/sites/{site_id}/curtailment/group/{group_id} — Release a curtailment group (restores clamped power first)
POST /v1/sites/{site_id}/bess/{bess_id}/optimize — Ask the AI to optimize this unit's dispatch
POST /v1/sites/{site_id}/bess/optimize-all — Optimize all units
POST /v1/sites/{site_id}/bess/schedules/{schedule_id}/approve — Approve a proposed dispatch schedule
POST /v1/sites/{site_id}/bess/schedules/{schedule_id}/reject — Reject a proposed dispatch schedule
POST /v1/sites/{site_id}/bess/schedules/approve-all — Approve all proposed schedules (?target_date)
PUT /v1/sites/{site_id}/bess/schedules/{schedule_id}/hours/{hour} — Edit one hour of a proposed schedule
POST /v1/sites/{site_id}/alerts/{alert_id}/acknowledge — Acknowledge an alert
POST /v1/sites/{site_id}/alerts/{alert_id}/resolve — Resolve an alert
POST /v1/sites/{site_id}/work-orders — Create a work order
PUT /v1/sites/{site_id}/work-orders/{wo_id} — Update a work order
PUT /v1/sites/{site_id}/work-orders/{wo_id}/items/{item_id} — Update a work-order checklist item
POST /v1/sites/{site_id}/work-orders/{wo_id}/approve — Approve a completed work order
PUT /v1/sites/{site_id}/om/notifications/{notification_id}/read — Mark an O&M notification read
POST /v1/sites/{site_id}/defects — Log a defect
PUT /v1/sites/{site_id}/defects/{defect_id} — Update a defect
POST /v1/sites/{site_id}/reports/subscriptions — Create a report subscription
DELETE /v1/sites/{site_id}/reports/subscriptions/{sub_id} — Delete a report subscription
PATCH /v1/sites/{site_id}/reports/subscriptions/{sub_id} — Update a report subscription
POST /v1/sites/{site_id}/reports/subscriptions/{sub_id}/run — Run a report subscription now