Skip to main content
A canonical action is the single body shape every device push accepts, regardless of OEM and regardless of device type. Build it from the device’s read response, post it, get the action id back. The same shape works for immediate dispatch, scheduled dispatch, and slots inside a schedule, and it works whether the device on the other end is a battery, an EV charger, or a thermostat. Agents do not click buttons. They read a response, choose a verb, build the parameters, and post. One read and one write are enough to drive any supported device, and the read teaches the write. A developer who learns the loop on a battery already knows it for an EV charger. The action push surface covers batteries, EV chargers, and thermostats. Solar inverters and vehicles are read-only: a POST /solar-inverter/{deviceId} or POST /vehicle/{deviceId} returns 422 DIRECT_ACTION_UNSUPPORTED. Use those families for monitoring; control the surrounding system via the writable device types. The JSON snippets on this page show only the action grammar and the relevant slices of the device read. Every real API response is wrapped in { success, data, meta }: the action body lands under data, and the device read’s state, commands, and settings all sit inside data. See error envelope for the canonical wrapper and the failure variant.

​
The action shape

{
  "action": {
    "command": "charge",
    "parameters": {
      "power": { "value": 3.0, "unit": "kw" },
      "target": { "value": 80, "unit": "percent" }
    },
    "start": "2026-06-01T18:00:00",
    "end": "2026-06-01T22:00:00"
  },
  "onConflict": "cancel_and_replace"
}
command selects the variant. parameters carries the mode’s inputs. start and end declare temporal intent. onConflict resolves collisions with active actions on the same device. Every field you send is either honoured, validated, or rejected. No keys are silently discarded.

​
Command vocabulary is intent, not feature flags

A command names an intent the device should pursue, not a button on a vendor app. The verb is the same canonical token whichever manufacturer answers, and the request shape is the same whichever device type answers. Each device type defines its own set of commands, drawn from one shared design language. The canonical battery surface defines six commands:
CommandMeaning
chargeDirect imperative. Charge from grid or solar, optionally bounded by target and power.
dischargeDirect imperative. Discharge to load or grid, optionally bounded by target and power.
idlePause charge and discharge. The battery sits.
auto.balancedOptimise for self-consumption. Charge when solar is plentiful, discharge when the home needs it.
auto.reserveReserve capacity for grid outage. Stay charged above the reserve floor.
auto.exportMaximise grid export. Discharge when the export tariff is attractive.
The EV charger defines two:
CommandMeaning
chargeBegin or resume charging the connected vehicle.
idlePause charging, holding the session.
The thermostat defines five:
CommandMeaning
heatActively heat to a target temperature.
coolActively cool to a target temperature.
autoMaintain a comfort band: heat below heatSetpoint, cool above coolSetpoint.
idlePause all heating and cooling.
follow_scheduleResume the device’s native program, relinquishing any active override.
The vocabulary is shared on purpose. idle is the canonical stop verb everywhere: it pauses a battery, pauses a charging session, and pauses heating and cooling, so an agent that learns “send idle to stop” applies it across every device type. target is the canonical “aim for this level” parameter: a battery charges to a target percent, a thermostat heats to a target degree. The same name, the same {value, unit} shape, a different physical quantity carried by the unit. Direct commands (charge, discharge, heat, cool, idle) are explicit instructions; the auto commands (auto.balanced, auto.reserve, auto.export, and the thermostat’s auto) name a device’s own self-managing mode in canonical vocabulary. A command present in the device’s commands map is supported. Absent means rejected. There is no supported: boolean field. See capabilities for how each device declares its subset.
Coming soon. Live control for EV chargers and thermostats. The sandbox environment runs the full command surface end to end, so you can build and test the entire integration. A live EV charger or thermostat push returns 422 COMMAND_NOT_SUPPORTED until the live path opens; battery control is live.
The same body shape carries every command. Reading once and writing once works regardless of which device type you point at: 
// EV charger: begin charging
{ "action": { "command": "charge" } }

// Thermostat: heat to 21°C
{ "action": { "command": "heat", "parameters": { "target": { "value": 21, "unit": "celsius" } } } }

// Thermostat: hold a comfort band
{
  "action": {
    "command": "auto",
    "parameters": {
      "heatSetpoint": { "value": 20, "unit": "celsius" },
      "coolSetpoint": { "value": 24, "unit": "celsius" }
    }
  }
}
The envelope, the command selector, the {value, unit} parameters, and the onConflict resolution are identical to the battery example above. Only the verbs and the parameter names differ, and the device tells you those on the read.

​
Self-documenting parameters

Every numeric parameter is a Quantity: { value, unit }. The unit travels with the value, so 80 is never ambiguous between percent, kilowatts, or amps. 
{ "value": 80, "unit": "percent" }
{ "value": 3.5, "unit": "kw" }
{ "value": 10, "unit": "percent" }
Parameters are scoped to the command that accepts them, and the device read declares the set. Three exist on the battery surface: target, power, reserve. target is an upper bound for charge and a lower bound for discharge. power caps the rate. reserve preserves a state-of-charge floor while the mode runs. The thermostat reuses target for heat and cool, and adds heatSetpoint and coolSetpoint for the auto comfort band. The EV charger’s charge and idle take no parameters at all. The shape is always {value, unit}; the unit (percent, kw, celsius) tells you the quantity. Send a unit the device does not accept and the API returns 422 UNSUPPORTED_UNIT. Send a parameter the mode does not accept and you get 422 UNSUPPORTED_PARAMETER with a deviceCapabilities snapshot in details, so you can fix the call in one round trip. Send a value outside the declared range and you get 422 PARAMETER_OUT_OF_RANGE; the bounds live on the device read, not in the request schema. See error envelope for the full list.

​
Per-mode execution support

Each command on a device declares an execution array drawn from { "immediate", "scheduled", "windowed" }. Each token names a distinct request shape:
TokenRequest shapeMeaning
immediateNo startFire on receipt.
scheduledstart onlyDefer firing until start.
windowedstart and endRun between start and end, then revert.
A push whose shape does not match the mode’s execution array returns 422 EXECUTION_NOT_SUPPORTED with details: { requestedExecution, supportedExecution }. On a battery, auto.balanced declares ["immediate", "scheduled"] (no end makes sense for a long-running mode), while charge may declare ["immediate", "scheduled", "windowed"]. EV charger and thermostat commands also declare scheduling shapes: an EV charger’s charge and a thermostat’s heat/cool declare ["immediate", "scheduled", "windowed"], while idle and the thermostat’s auto accept ["immediate", "scheduled"]. The thermostat’s follow_schedule is ["immediate"] only. The array tells you, per command, exactly which shapes the device runs, so you never have to assume. The execution shape also decides the action’s starting lifecycle state. An immediate push (no start) lands in acknowledged and reaches completed or failed from there. A deferred or windowed push (with start, optionally with end) waits in scheduled until the fire time, then advances to acknowledged and on. scheduled is a state only deferred and windowed pushes pass through; an immediate push never sits there.
Read the device once. Pick a command. Inspect its execution array. Build the request shape that array allows. The API tells you what is acceptable, so you do not need to know per-OEM physics.

​
Conflict resolution

Only one non-terminal action can target a device at a time. Submit a new push while another is active or scheduled and onConflict decides what happens:
StrategyBehaviour
cancel_and_replaceCancel the conflicting action, run the new one.
queue_afterDefer the new action’s start to the conflict’s end.
OmittedReturn 409 with the conflicting action ID and the available strategies.
A device honours the strategies that make sense for it. cancel_and_replace works everywhere. queue_after is honoured only where the device declares it. EV chargers and thermostats declare only cancel_and_replace, so a queue_after push to one returns 422 STRATEGY_NOT_SUPPORTED. The 409 body lists the strategies a given device accepts, so you never guess. The model is documented end-to-end on conflict resolution.

​
Datetime and time-window contract

start and end are plant-local wall-clock ISO 8601 strings: YYYY-MM-DDTHH:MM:SS. No timezone offset, no Z. The platform interprets the wall-clock in the device’s plant timezone, so a customer in any timezone reads “5pm at the device” the same way. Any offset (Z, +01:00, -05:00) is rejected at the API boundary — the error explains how to drop the suffix. Relative durations (30m, 1.5h) are accepted on start only and normalised to absolute instants at request time. start must be in the future and within 30 days. end must be after start in wall-clock terms (DST gaps are handled — see below). Time windows are right-open intervals [start, end). 
{
  "command": "charge",
  "parameters": { "power": { "value": 5, "unit": "kw" } },
  "start": "30m",
  "end": "2026-06-01T22:00:00"
}
DST behaviour: wall-clocks inside a spring-forward gap (e.g. 02:30 on the night the UK jumps from 01:00 GMT to 02:00 BST) are rejected with START_NONEXISTENT_WALL_CLOCK. Wall-clocks that occur twice (autumn fall-back overlap) resolve to the first occurrence (the pre-transition offset). Submit a wall-clock outside the overlap if the second occurrence is required. Responses normalise start and end to absolute UTC. You send 2026-06-10T22:00:00 for a plant in Europe/London during BST, the action read returns 2026-06-10T21:00:00.000Z. The wall-clock you submitted is preserved in plant time, then resolved against the plant’s IANA timezone for storage and dispatch. The UTC echo is the dispatch-ready instant, not a re-interpretation of your intent.

​
Capability introspection

The device read returns the same vocabulary you post back. A GET /battery/{deviceId} carries commands alongside the rest of the device record under data: 
{
  "success": true,
  "data": {
    "id": "device_abc123",
    "vendor": "example_vendor_a",
    "sync": { "available": true, "lastPulledAt": "2026-06-01T10:30:00.000Z" },
    "metadata": { "model": "Hybrid 5kWh", "source": "cache" },
    "state": { "status": "charging", "level": 50, "capacity": 10.4, "chargeRate": 2.4, "dischargeLimit": 10, "currentMode": "charge" },
    "conflictStrategies": ["cancel_and_replace", "queue_after"],
    "commands": {
      "charge": {
        "parameters": {
          "power": { "unit": "kw", "min": 0, "max": 5.0 },
          "target": { "unit": "percent", "min": 10, "max": 100 }
        },
        "execution": ["immediate", "scheduled", "windowed"]
      },
      "auto.balanced": {
        "parameters": {},
        "execution": ["immediate", "scheduled"]
      }
    },
    "settings": { "discharge_floor": { "value": 10, "unit": "percent" } },
    "lastAction": null,
    "currentSchedule": null
  },
  "meta": { "requestId": "req_8a2Bf3kP", "environment": "live", "timestamp": "2026-06-01T10:30:00.000Z", "latencyMs": 12 }
}
data.commands.charge.parameters on the read maps directly to action.parameters on the write. The bounds (min, max) and units come straight from the device’s declared capabilities. Bounds are optional; an absent min or max means open-ended on that side, as documented in capabilities. Presence in the map means supported. Absence means rejected.

​
Actions are not settings

Actions answer “what should the device do?” Settings answer “within what bounds should it operate?” Actions are time-boundable, conflict-able, and audited. Settings are persistent, non-conflicting, and fire-and-forget. The litmus test: “does this make sense with a time window?” You can say “charge from 6pm to 10pm”. You would never say “set the safety reserve to 10% from 6pm to 10pm”. If it is time-boundable, it is an action. The boundary drives where a capability lives. An EV charger’s maximum charging power is a ceiling the charger operates under, not an intent it pursues, so it is the max_charge_rate setting (in kw), written through POST /ev-charger/{deviceId}/settings, exactly as the battery’s max_charge_rate is. The charger’s two actions stay clean intents: charge and idle. You set the ceiling once, then start and stop sessions against it. Actions run through POST /battery/{deviceId}, POST /ev-charger/{deviceId}, or POST /hvac/{deviceId} and create an audit record. Settings, on the device types that declare a settings surface (POST /battery/{deviceId}/settings and POST /ev-charger/{deviceId}/settings), do not. A thermostat exposes commands but no settings surface. See the API reference for the full surface.

​
Frequently asked questions

​
Do EV chargers and thermostats use the same push shape as batteries?

Yes. Every device type accepts the same { action: { command, parameters }, onConflict } body. The verbs differ by type: a battery takes charge, discharge, idle, and the auto modes; an EV charger takes charge and idle; a thermostat takes heat, cool, auto, idle, and follow_schedule. The envelope, the {value, unit} parameters, and the conflict resolution are identical. Read the device’s commands map to see which verbs it accepts.

​
What is auto.balanced?

auto.balanced is a canonical battery mode that names the device’s self-managing self-consumption mode under a shared name. It is one of three auto modes (auto.balanced, auto.reserve, auto.export) that every supported battery speaks. The client sends the same request shape across every device.

​
How do I push an action with a time window?

Send start and end as plant-local wall-clock ISO 8601 strings (YYYY-MM-DDTHH:MM:SS, no offset, no Z) in the action body. The command must declare windowed in its execution array; charge and discharge do, the auto modes typically do not. The action runs from start, then reverts at end. ISO strings with offsets (Z, +01:00, etc.) are rejected — the platform interprets the wall-clock in the device’s plant timezone. Sub-minute windows are rejected on devices whose schedulers operate at minute resolution.

​
What is the difference between command and parameters in the action body?

command is the verb the device should pursue, drawn from the set its type defines (a battery’s charge, an EV charger’s charge, a thermostat’s heat). parameters is the bag of inputs that verb accepts. On a battery’s charge: target (an SOC bound), power (a rate cap), reserve (an SOC floor). On a thermostat’s heat: target (a temperature). Some commands accept none; a battery’s auto modes and an EV charger’s charge carry no parameters, since their behaviour is intent-only.

​
Can I send a charge and an auto.balanced action at the same time?

Only one non-terminal action targets a device at a time. Submit auto.balanced while a charge is scheduled or acknowledged and the API returns 409 CONFLICT unless onConflict resolves it. Use cancel_and_replace to drop the existing action and run the new one, or queue_after to defer the new action until the existing one ends. One active intent per device.

​
What happens if I send a parameter the device does not support?

The API returns 422 UNSUPPORTED_PARAMETER with details.unsupportedParameters[] and a deviceCapabilities snapshot. The snapshot has the same shape as the GET response, so the caller rebuilds the request from the rejection without a second fetch. Sending an unknown unit returns 422 UNSUPPORTED_UNIT with the supported units. Sending a value outside the declared range returns 422 PARAMETER_OUT_OF_RANGE.

Capabilities

How the device tells you which commands, parameters, and units it accepts.

Conflict Resolution

How onConflict handles overlap and 409s.

Scheduling

Push as the only execution primitive. Schedules as coordinators.

Error Envelope

The shape of every rejection, including UNSUPPORTED_UNIT and EXECUTION_NOT_SUPPORTED.
For a worked walkthrough, see the cookbook: schedule a charge for later.