Devices

A device represents a physical energy asset (battery, inverter, EV charger, heat pump, meter, …) that sits within a site. The customer API exposes three read endpoints for devices: metadata, telemetry, and the overlay plan.

Get device

GET /api/v2/devices/{synthId}

Returns metadata for a single device the authenticated customer owns. Use GET /api/v2/devices to list the synthId values available to you.

Response fields

Field	Type	Description
`id`	string	The device's synthId.
`deviceType`	string	Device model identifier (e.g. `VirtualLunarInverter`).
`siteId`	string	The site the device belongs to.
`provisionStage`	string	`unprovisioned`, `provisioning`, or `provisioned`.
`physicalId`	string	Hardware serial number or physical identifier.
`publishTo`	array	Partners this device is currently publishing telemetry to.
`controlOptions`	object	Control settings: `minSOC`, `maxSOC`, `backupOnWeatherAlerts`, `scheduledSmartModeActivationTime`.
`attributes`	object	Device-level metadata: `tariffID`, `maxCapacity_kWh`, `location`, `FITStart`, `FITExpiration`, and others.

Example request

curl -s \
  -H "Authorization: Bearer ${access_token}" \
  "https://${api_base_url}/api/v2/devices/${synthId}"

Example response

{
  "id": "lunar_hc-abc-inv-1",
  "deviceType": "VirtualLunarInverter",
  "siteId": "lunar_hc-abc",
  "provisionStage": "provisioned",
  "physicalId": "SN-001234",
  "publishTo": [],
  "controlOptions": {
    "minSOC": 0.1,
    "maxSOC": 1.0,
    "backupOnWeatherAlerts": false
  },
  "attributes": {
    "maxCapacity_kWh": 10.0
  }
}

Get telemetry

GET /api/v2/devices/{synthId}/telemetry

Returns time-bucketed measurements for a single device stream. See the Telemetry concept page for a full guide — including which sensor IDs to use (usually a derived ID from the site topology, not the bare device synthId), parameter reference, channel definitions, and worked examples.

Quick parameter reference

Parameter	Required	Description
`interval`	Yes	ISO 8601 time interval, e.g. `2026-04-01T00:00:00Z/2026-04-02T00:00:00Z` or `2026-04-01T00:00:00Z/PT24H`. Times must be UTC.
`resolution`	No	`PT15M` (default), `PT1H`, or `P1D`.
`include`	No	`default` (power, SoC, state), `energy`, or `default,energy`.
`aggregation`	No	`default` (time-window average) or `latest` (most recent value per bucket).

Get overlay plan

GET /api/v2/devices/{synthId}/plans/overlay

Returns the scheduled overlay plan for a device — the sequence of commands that will be executed on the device in order, each active for durationMinutes before the next begins.

Use this endpoint to answer questions like "what will my device do next?" or "is there a charge schedule set?"

If no overlay plan is active, startTime is a sentinel value in the past and commands is an empty array.

Response fields

Field	Type	Description
`startTime`	string (ISO 8601)	When the first command takes effect.
`commands`	array	Ordered list of commands to execute.

Each command has a kind and a durationMinutes. Supported kinds:

Kind	Description
`selfConsumption`	Optimise for self-consumption (charge from excess solar, discharge to home).
`idle`	Hold — do not charge or discharge. Accepts optional `socMin` / `socMax` bounds.
`setpoint`	Target a specific charge or discharge power in watts (`setpoint_W`).
`heatWater`	Heat water (heat-pump devices only).

Example request

curl -s \
  -H "Authorization: Bearer ${access_token}" \
  "https://${api_base_url}/api/v2/devices/${synthId}/plans/overlay"

Example response

{
  "startTime": "2026-05-12T00:00:00.000Z",
  "commands": [
    { "kind": "idle", "durationMinutes": 480 },
    { "kind": "selfConsumption", "durationMinutes": 240 },
    { "kind": "idle", "durationMinutes": 720 }
  ]
}