Capabilities

The canonical surface defines what the API accepts in general. Every device declares which subset of that surface it actually supports. One read is enough to know which commands fire, which parameters apply, which units are accepted, and which execution shapes the device can run. That declaration is the contract for that specific device.

Capabilities live on the read response

There is no separate /capabilities endpoint. The declaration ships inside the device read: GET /battery/{deviceId}, GET /ev-charger/{deviceId}, GET /hvac/{deviceId}, and their list endpoints all carry the commands block. One read returns state and commands, plus settings on the device types that declare a settings surface (battery and EV charger; a thermostat has commands but no settings). Settings ride the single-device read; list views carry commands, not settings:

{
  "success": true,
  "data": {
    "id": "device_abc123",
    "vendor": "foxess",
    "sync": { "available": true, "lastPulledAt": "2026-06-01T10:14:23.000Z" },
    "metadata": { "model": "FoxESS H1-5.0-E", "source": "cache" },
    "state": { "status": "charging", "level": 50, "capacity": 10.4, "chargeRate": 2.4, "dischargeLimit": 10 },
    "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.balance": { "parameters": {}, "execution": ["immediate", "scheduled"] }
    },
    "settings": {
      "discharge_floor": { "value": 10, "unit": "percent", "min": 0, "max": 100 }
    },
    "lastAction": null,
    "currentSchedule": null
  },
  "meta": { "requestId": "req_8a2Bf3kP", "environment": "live", "timestamp": "2026-06-01T10:14:23.000Z", "latencyMs": 12 }
}

The shape mirrors the push body. commands.charge.parameters.power on the read maps directly to action.parameters.power on the write. See canonical actions. conflictStrategies advertises the onConflict values the device accepts when a new push collides with an action already in flight. Read it before sending onConflict: a strategy outside this list is rejected with 422 STRATEGY_NOT_SUPPORTED. It is present on every commandable device type and absent on read-only types, which have no push to conflict. See conflict resolution.

The same shape across device types

The commands block is one contract, not a battery-specific one. The EV charger declares its commands the same way. Its charge carries the rate caps and stop conditions; idle and the three charging strategies carry nothing:

{
  "success": true,
  "data": {
    "id": "device_ev789",
    "vendor": "example_vendor_a",
    "sync": { "available": true, "lastPulledAt": "2026-06-01T10:14:24.000Z" },
    "metadata": { "model": "7kW AC Charger", "source": "cache" },
    "state": {
      "status": "charging",
      "isConnected": true,
      "isCharging": true,
      "currentPower": 7.2,
      "maxCurrent": 32,
      "powerRateLimit": 7.4,
      "sessionEnergy": 12.6,
      "phases": 1,
      "voltage": 230,
      "activeControlMode": "charge"
    },
    "conflictStrategies": ["cancel_and_replace", "queue_after"],
    "sessions": true,
    "commands": {
      "charge": {
        "parameters": {
          "power":   { "unit": "kw", "min": 1.4, "max": 22, "step": 0.1 },
          "current": { "unit": "amps", "min": 6, "max": 32, "step": 1 },
          "energy":  { "unit": "kwh", "min": 1, "max": 100 }
        },
        "execution": ["immediate", "scheduled", "windowed"]
      },
      "idle":                      { "parameters": {}, "execution": ["immediate", "scheduled"] },
      "auto.charge_tariff":        { "parameters": {}, "execution": ["immediate", "scheduled"] },
      "auto.charge_surplus_only":  { "parameters": {}, "execution": ["immediate", "scheduled"] },
      "auto.charge_surplus_first": { "parameters": {}, "execution": ["immediate", "scheduled"] }
    },
    "settings": {
      "max_charge_rate":    { "value": 11, "unit": "kw", "min": 0, "max": 50, "step": 0.1 },
      "max_charge_current": { "value": 32, "unit": "amps", "min": 6, "max": 32, "step": 1 },
      "cable_lock":         { "value": true }
    },
    "vehicle": { "id": "device_veh456", "links": { "self": "/vehicle/device_veh456" } },
    "lastAction": null,
    "currentSchedule": null
  },
  "meta": { "requestId": "req_8a2Bf3kP", "environment": "live", "timestamp": "2026-06-01T10:14:24.000Z", "latencyMs": 14 }
}

This charger declares target on none of its commands. A charger can only stop at a state of charge it can read, and most cannot see inside the car, so they declare energy and count on their own meter instead. Absence is the contract: send target here and it is refused with 422 UNSUPPORTED_PARAMETER. vehicle names the car this charger is filling, when the platform can tell which one it is. It is a pointer, not a copy: the state of charge and range live on the vehicle resource at links.self. It is null whenever the answer would be a guess. The thermostat does too. Its heat and cool commands take a target temperature; auto.maintain takes a heatSetpoint and coolSetpoint comfort band; idle and auto.schedule take nothing:

{
  "success": true,
  "data": {
    "id": "device_hvac456",
    "vendor": "example_vendor_b",
    "sync": { "available": true, "lastPulledAt": "2026-06-01T10:14:25.000Z" },
    "metadata": { "model": "Smart Thermostat v3", "source": "cache" },
    "state": { "temperature": 20.5, "active": true, "heatSetpoint": 20, "coolSetpoint": 24, "holdType": "schedule", "mode": "heat" },
    "conflictStrategies": ["cancel_and_replace"],
    "commands": {
      "heat": {
        "parameters": { "target": { "unit": "celsius", "min": 10, "max": 35 } },
        "execution": ["immediate", "scheduled", "windowed"]
      },
      "cool": {
        "parameters": { "target": { "unit": "celsius", "min": 10, "max": 35 } },
        "execution": ["immediate", "scheduled", "windowed"]
      },
      "auto.maintain": {
        "parameters": {
          "heatSetpoint": { "unit": "celsius", "min": 10, "max": 35 },
          "coolSetpoint": { "unit": "celsius", "min": 10, "max": 35 }
        },
        "execution": ["immediate", "scheduled"]
      },
      "idle": { "parameters": {}, "execution": ["immediate", "scheduled"] },
      "auto.schedule": { "parameters": {}, "execution": ["immediate"] }
    },
    "lastAction": null,
    "currentSchedule": null
  },
  "meta": { "requestId": "req_8a2Bf3kP", "environment": "live", "timestamp": "2026-06-01T10:14:25.000Z", "latencyMs": 18 }
}

The keys differ because the commands differ, but the shape is identical: a map of commands, each with a parameters map of units and bounds, and an execution array. Read the block, find the parameter bounds, build a valid push. The loop is the same whichever device answers. Commands are keyed by their canonical name; the read returns only canonical vocabulary. Conflict resolution is device-level, not per-command: one action is active per device at a time. Any new command conflicts with the one in flight, whether it is a different mode on the same device or the same mode again, and onConflict resolves the overlap. There is no per-command grouping to reason about; the capability block tells you the commands and their bounds, the conflict model tells you how concurrent requests resolve.

Coming soon. Live control for EV chargers and thermostats. The sandbox environment serves the full commands and settings surface so you can build the whole integration against it. A live EV charger or thermostat push returns 503 NOT_YET_AVAILABLE until the live path opens; battery control is live.

Some device types are read-only

Not every device type accepts commands. A solar inverter and a vehicle expose state, sync status, and metadata, and no commands block at all:

{
  "success": true,
  "data": {
    "id": "device_solar321",
    "vendor": "enphase",
    "sync": { "available": true, "lastPulledAt": "2026-06-01T10:14:23.000Z" },
    "metadata": { "model": "IQ8+", "source": "cache" },
    "state": { "status": "producing", "currentPower": 4.2, "producing": true, "energyTotal": 18400 }
  },
  "meta": { "requestId": "req_8a2Bf3kP", "environment": "live", "timestamp": "2026-06-01T10:14:23.000Z", "latencyMs": 22 }
}

The absence is the contract. The canonical surface for these device types defines reads and no push actions, so the read carries everything they support. A push against a read-only device type has no command to name. This is complete, not a gap: the device declares the full surface it offers, and that surface is state.

Presence-based support

A capability is supported iff its key is present. Absent means rejected.

{ "commands": { "charge": "...", "auto.balance": "..." } }

A push for discharge against this device returns 422 UNSUPPORTED_MODE. A push for charge with a reserve parameter (when parameters.reserve is absent on the read) returns 422 UNSUPPORTED_PARAMETER. There is no supported: boolean field, and no “parameter exists but is disabled” middle state. Either the device declares it and honours it, or the API rejects with structured detail you can act on. An empty parameters: {} is a valid declaration. It means the command is supported and takes no parameters. auto.* commands typically declare empty parameters because their behaviour is intent-only; strategy parameters belong to the underlying optimisation, not to the canonical request.

Per-mode execution shapes

Each command declares an execution array drawn from { "immediate", "scheduled", "windowed" }:

Token	Request shape	Validation
`immediate`	No `start`	Allowed only if `"immediate"` is in the array.
`scheduled`	`start` only	Allowed only if `"scheduled"` is in the array.
`windowed`	`start` and `end`	Allowed only if `"windowed"` is in the array.

A request shape that does not match the array returns 422 EXECUTION_NOT_SUPPORTED with details: { requestedExecution, supportedExecution }. Validation is per-mode, not per-device: a device may accept auto.balance immediately but require charge to be windowed, and the capability response expresses that directly.

Units and bounds

Numeric parameters carry a unit and optional bounds:

{ "power": { "unit": "kw", "min": 0, "max": 5.0 } }

Field	Behaviour
`unit`	Required. Sending a different unit returns 422 `UNSUPPORTED_UNIT`.
`min`	Optional. Open-ended on the lower side if absent.
`max`	Optional. Open-ended on the upper side if absent.
`step`	Optional. The increment the value must land on, counted from `min` (or from 0 when no `min` is declared). Absent means any value inside the bounds is accepted.

A push value outside the declared range returns 422 PARAMETER_OUT_OF_RANGE, and so does one inside the range but off the step grid. A charger declaring { "unit": "kw", "min": 1.4, "max": 22, "step": 0.1 } accepts 4.2 and refuses 4.25. Round to the grid before sending; the same three bounds ride on settings values, so the rule is one rule. The bounds you act on come from the device read, not from a fixed request schema. The thermostat’s target and heatSetpoint follow the same rule as the battery’s power: read the bound off commands, build a value inside it, post. Because the bound lives on the read, it is per-device, so a value valid for one device can be rejected by another of the same type. Bounds reflect the device’s documented operating range merged with Amps-side safety. They do not change the canonical name or unit; they only constrain the value.

Settings

settings declares persistent device configuration with current values and bounds. It sits beside commands on the read, and like commands it is a per-device-type surface: settings are how a device operates, not what it does. The battery’s canonical writable surface:

Setting	Type	Unit	Meaning
`safety_reserve`	number	percent	Lowest SOC the battery will reach, even during a power cut.
`discharge_floor`	number	percent	Lowest SOC during normal operation.
`charge_ceiling`	number	percent	Highest SOC the battery will charge to.
`export_limit`	number	watts	Maximum power the battery sends to the grid.
`max_charge_rate`	number	amps	Maximum charge current.
`max_discharge_rate`	number	amps	Maximum discharge current.

The EV charger has a settings surface too. It rides the same {value, unit} shape and the same POST /ev-charger/{deviceId}/settings write path as the battery’s:

Setting	Type	Unit	Meaning
`max_charge_rate`	number	kw	Ceiling the charger draws under, in kilowatts.
`max_charge_current`	number	amps	The same ceiling in amperes, for a charger that thinks in current.
`cable_lock`	boolean	—	Whether the cable stays locked to the charger.

A ceiling is configuration, not an intent, so it lives here rather than as a push parameter, which keeps the charger’s five commands clean intents. See canonical actions on the actions-versus-settings boundary. Read-only settings (e.g., scheduler_enabled) appear in the read response but reject writes with 422 READ_ONLY_SETTING. Unknown setting keys reject with 422 UNSUPPORTED_SETTING. Writes use a separate endpoint and a sparse-map body. See What to expect on read-write parity. max_charge_rate and max_charge_current are one rate ceiling written in two units. A charger that holds a single rate register cannot take both in one request without one silently winning, so it refuses the pair with 422 UNSUPPORTED_SETTING_COMBINATION and names them in details.conflictingSettings. Which settings collide is a property of the device, so send one of a colliding pair and read details if a request comes back refused.

Computed at read time

The capability declaration is computed at read time, not cached separately; an updated declaration takes effect on the next read. Only canonical names appear in the response.

Availability tiers

Devices graduate from sandbox-only simulations to general availability. Sandbox devices are visible only in the sandbox environment. Generally-available devices are visible to everyone in live. Tiers in between gate visibility while an integration is firming up; promotion to general requires no per-customer changes.

How agents use this

A read-then-build-then-write loop is what makes agentic device control mechanical. The agent does not need to know which OEM is on the other end; the device tells it what is acceptable and the agent picks a valid request shape. This is the “build once, control any device” property in code.

const device = await api.get(`/battery/${deviceId}`);
const cmd = device.commands.charge ? 'charge' : 'auto.balance';
const spec = device.commands[cmd];

const parameters = Object.fromEntries(
  Object.entries(spec.parameters).map(([name, c]) => [name, { value: chooseValue(name, c), unit: c.unit }])
);
const shape = spec.execution.includes('immediate') ? {} : { start: '30m', end: '1h' };

await api.post(`/battery/${deviceId}`, { action: { command: cmd, parameters, ...shape } });

No OEM-specific knowledge needed, and no device-type-specific knowledge either. Swap the endpoint to /ev-charger/{id} or /hvac/{id} and the loop is unchanged: read commands, pick a command the device declares, build parameters inside the declared bounds, post. The device tells the agent what is acceptable, the agent builds and posts. Build once, control any device.

Frequently asked questions

How do I check if a battery supports auto.balance?

Read the device with GET /battery/{deviceId} and inspect commands. If auto.balance is a key on the commands map, the device supports it. If absent, a push for auto.balance returns 422 UNSUPPORTED_MODE. There is no supported: boolean field; capability is declared by presence. The same rule holds for parameters and units: present means supported, absent means rejected.

Where is the capability response defined?

Capabilities live on the device read response, not at a separate /capabilities endpoint. GET /battery/{deviceId}, GET /ev-charger/{deviceId}, and GET /hvac/{deviceId} all return commands in one body alongside state. The shape is one contract across device types: each command is keyed by its canonical name and carries a parameters map of units and bounds and an execution array. One read is enough to construct a valid command without external documentation.

Do all device types support commands?

No, and the read response tells you which do. A battery, EV charger, and thermostat return a commands block declaring the actions they accept. A solar inverter and a vehicle return state with no commands block, because the canonical surface for those device types is read-only. The absence is the contract: the device declares everything it offers, and for these types that is reads.

Can capabilities change at runtime?

Yes. The capability declaration is computed at read time, not cached separately, so an updated declaration takes effect on the next read. State values change continuously; the capability declaration changes when the platform ships an update. New capabilities surface automatically; clients that already poll the read pick them up without code changes.

What are availability tiers?

Canonical Actions

The action shape that mirrors the capability response.

Device State

Where the capability response lives on the API.

What to expect

Why presence-based support and self-describing parameters.

Error Envelope

UNSUPPORTED_MODE, UNSUPPORTED_PARAMETER, READ_ONLY_SETTING.

For agent-driven walkthroughs that ground requests in capability data, see the MCP examples.

Get Started

Concepts

API Reference

Guides

Quick reference

More

Capabilities live on the read response

The same shape across device types

Some device types are read-only

Presence-based support

Per-mode execution shapes

Units and bounds

Settings

Computed at read time

Availability tiers

How agents use this

Frequently asked questions

How do I check if a battery supports auto.balance?

Where is the capability response defined?

Do all device types support commands?

Can capabilities change at runtime?

What are availability tiers?

Canonical Actions

Device State

What to expect

Error Envelope

​Capabilities live on the read response

​The same shape across device types

​Some device types are read-only

​Presence-based support

​Per-mode execution shapes

​Units and bounds

​Settings

​Settings that cannot share a request

​Computed at read time

​Availability tiers

​How agents use this

​Frequently asked questions

​How do I check if a battery supports auto.balance?

​Where is the capability response defined?

​Do all device types support commands?

​Can capabilities change at runtime?

​What are availability tiers?

​Related concepts

Canonical Actions

Device State

What to expect

Error Envelope

Capabilities live on the read response

The same shape across device types

Some device types are read-only

Presence-based support

Per-mode execution shapes

Units and bounds

Settings

Settings that cannot share a request

Computed at read time

Availability tiers

How agents use this

Frequently asked questions

How do I check if a battery supports auto.balance?

Where is the capability response defined?

Do all device types support commands?

Can capabilities change at runtime?

What are availability tiers?

Related concepts