Capabilities

TL;DR

• GET /devices returns each device's capabilities[] — this is the only source of truth for what a device can do right now
• PUT /devices/{id}/{capabilityName} to write — returns 202 Accepted (async), then re-fetch the device to see the result
• If a capability has interventions[], it's blocked — show the user what to do (e.g. re-authenticate, upgrade subscription)
• Capability not in the array? The device doesn't support it. Don't treat it as an error.
• Capabilities can carry an options object with per-device guardrails (e.g. allowed amperage range) — validate inputs against it, see Capability options
• time-control schedule times must be exact five-minute grid points (for example, 14:35:00)
• target-control = guaranteed minimum runtime inside a daily window (auto-planned); time-control = fixed on/off schedules — see target-control details and time-control details
• See the Capability Reference for all payloads, actionDetails per action, and which actions work on which device category

This documentation is intended for B2B customers of the clever-PV Connect API and explains the capability concept from an API perspective.

Basic idea

A device has a list of capabilities. A capability describes one ability of the device (e.g., turning on/off, setting a charge limit, displaying SoC, connecting a vendor).

• Read: Capabilities are returned via the device endpoints as part of the device object.
• Write: Some capabilities can be updated/executed via a generic "PUT capability" endpoint.
• Important: Capabilities are dynamic (see section "Dynamics: capabilities are not static").

API objects (response view)

Device (simplified)

A device contains, among other fields, model and capabilities.

Code
{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "My Device",
  "externalId": "vendor-specific-id",
  "model": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Vendor Model Display Name",
    "category": "car",
    "vendor": {
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "Vendor Display Name"
    }
  },
  "capabilities": [
    {
      "name": "core",
      "data": { "name": "My Device", "connectivityStatus": "online" },
      "options": { },
      "interventions": [ { "id": "authentication-required" } ]
    }
  ]
}

The core capability's connectivityStatus is one of:

• online — device is reachable and reporting.
• offline — device is unreachable (repeated polling failures, or onboarding not completed).
• connecting — device onboarded but has not reported any signal yet; status is still being determined.

Capability (response view)

Each capability is an object with:

• name: string, the unique capability name (e.g., core, connect, set-charge-limit)
• data: arbitrary JSON object (capability-specific; structure depends on the capability)
• options: arbitrary JSON object with capability-specific metadata (e.g., how the capability should be executed or). It may be empty or missing, and its shape is capability-dependent.
• interventions: list of blockers (see Interventions (blockers) – meaning & examples) that explain why a capability is currently not usable

Endpoints (read & write capabilities)

Read capabilities

• GET v1/users/{userId}/devices
  Returns a paginated list of devices (wrapper object) incl. capabilities:

Code
{
  "data": [ /* DeviceDto[] */ ],
  "cursor": "opaque-cursor",
  "size": 50,
  "total": 123,
  "hasMoreResults": true
}

• GET v1/users/{userId}/devices/{deviceId}
  Returns a device incl. capabilities.

Write/execute capabilities

• PUT v1/users/{userId}/devices/{deviceId}/{capability}
  • {capability} is the capability name (e.g., on-off, connect, set-charge-limit)
  • Request body is capability-specific (see "Capability Reference")
  • Response is 202 Accepted (asynchronous) – then fetch the device again via GET

Example (turn device on/off):

Code
PUT /v1/users/USER_ID/devices/DEVICE_ID/on-off
Content-Type: application/json

{ "state": "on" }

Response:

Code
202 Accepted

Dynamics: capabilities are not static

Capabilities can appear, disappear, or be blocked depending on:

• Device category & model (e.g., a car may have set-charge-limit, an electric meter may not)
• Vendor/onboarding flow (e.g., connect with Form/OIDC/OCPP options)
• Current device state (online/offline, data available, telemetry delayed)
• Subscription/product enablement (e.g., features may show subscription-upgrade-required)
• Setup completeness (e.g., home-location-required, connector-type-required)

Blocked vs unsupported:

• Blocked capability: The capability exists in capabilities[] but includes one or more interventions. It is present but not currently usable.
• Unsupported capability: The capability does not exist in capabilities[]. A PUT to that capability results in a capability-not-supported error.
• Not yet listed (no data): Setup and read-only capabilities whose data is not available yet are currently omitted from capabilities[] instead of being listed with empty data — e.g. home-location before a location is stored, display-estimated-range before the vehicle has reported a range, add-charging-location before the vendor contract is known. The corresponding setup intervention (e.g. home-location-required) is shown on the core capability. A PUT to such a setup capability is still accepted (202) if the device model supports it; the capability appears in capabilities[] after the write.

What "CapabilityData" means:

Most capabilities have a corresponding *CapabilityData (and for writable ones often *CapabilityUpdateData) schema that defines the shape of the JSON payload. This is the contract for what you receive in capabilities[].data and what you send in the PUT body for writable capabilities.

Swagger has no path per capability — writes all go through PUT /v1/users/{userId}/devices/{deviceId}/{capability}. Look up a capability's payload under its *CapabilityData / *CapabilityUpdateData schema.

How clients should handle this

• Treat capabilities as a server-driven contract: Do not assume a capability exists.
• If a capability is missing: The device cannot currently do it (or not for this user). Do not treat it as an error.
• If interventions are present: The capability exists, but is currently blocked. Use the intervention id to show the user the next action.
• Always re-fetch after PUT: After a 202 Accepted, fetch the device again via GET to see the new status/blocker. Some writes apply in more than one asynchronous step, so an immediate re-fetch can show a transitional state — compare the returned data against the values you sent and re-read after 1–2 s if they differ (see target-charging details for a concrete case).
• Be tolerant of unknown fields: In data, options, and enum values.

Interventions (blockers) – meaning & examples

Some capabilities include an interventions[] array that explains why the capability is currently blocked (even though it is present in capabilities[]). Each intervention has a stable id you can use to drive UI actions and troubleshooting.

For a full list of known intervention IDs and typical resolutions, see Interventions.

Capability options (dynamic guardrails)

Next to data, a capability can carry an options object with capability-specific metadata — most importantly the allowed input ranges for writes. Options are resolved per device (e.g. the amperage limits of the concrete wallbox model), so read them from the device response instead of hard-coding ranges. When a capability has no options, the field is omitted — always treat options as optional.

Capabilities that currently emit options:

Two things to build into your client:

• Validate against the options before sending. Where the server does enforce a range, a violation currently surfaces as 500 / errorCode: internalError rather than a proper 400 validation error — so client-side validation against the advertised options is the only way to give users a helpful message.
• Ranges without options: sun-share (sensible: 1–100), priority, and rated-capacity advertise no range and are not server-side validated — validate client-side.

Error handling (Problem Details)

The OpenAPI specification defines two different error response shapes:

• ProblemDetails (generic ASP.NET problem details; used by many endpoints)
• ConnectApiProblemDetails (partner-friendly problem details with type + errorCode + traceId + optional validation issues)

Which one you receive depends on the endpoint and status code.

ConnectApiProblemDetails shape (simplified)

Code
{
  "type": "capabilityNotSupported",
  "title": "Capability Not Supported",
  "status": 422,
  "detail": "Human readable message",
  "traceId": "00-...-...",
  "errorCode": "capabilityNotSupported",
  "issues": [
    { "field": "data.someField", "message": "must not be empty", "code": "NotEmptyValidator" }
  ],
  "extensions": { }
}

ProblemDetails shape (simplified)

Code
{
  "type": "https://example/problem-type",
  "title": "Bad Request",
  "status": 400,
  "detail": "Human readable message",
  "instance": "https://example/instance"
}

Relevant HTTP status codes for capability PUT

• 400: Request/validation failed (e.g., wrong type, missing required fields)
• 401: Unauthorized (token/app id/signature missing/invalid)
• 402: Payment required (feature/subscription required)
• 412: Precondition failed (e.g., consent/certificate missing)
• 422: Capability not supported (device does not support it / currently not executable)
• 500 with errorCode: "carLinkedToWallbox": the car is linked to a clever-PV wallbox (connector-type = cpvWallbox) and charging control lives on the wallbox device — see target-charging details. Treat the errorCode as the signal, not the status class.

How the optimization features fit together

The write capabilities fall into five groups. Within a group the capabilities depend on each other; across groups they combine (see the individual reference entries for the exact interplay):

• Master switch — smart-mode gates all optimization below (except time-control schedules); preferred-operating-mode stores the user-selected regime and force-disables everything on monitoring.
• PV surplus — solar-optimization (the on/off), tuned by rated-capacity (switch-on threshold), sun-share (minimum solar share), priority (who gets surplus first), switch-delay (debounce), and — on cars/wallboxes — charging-mode (regulation style).
• Price — price-control (threshold-based; cars, wallboxes, switches, heating rods) and price-optimization (thresholdless heat-pump variant). OR-combined with PV surplus.
• Battery SoC — soc-plan uses the home battery as a buffer for this consumer.
• Schedules & planners — time-control (fixed schedules, independent of smart-mode), target-control (runtime target; switches/heating rods), target-charging (energy/SoC target; cars/wallboxes).

Which devices typically have which capabilities?

This is guidance. The decisive factor is always what is returned in the device's capabilities[].

Car (vehicles)

• Typical (read): core, display-soc, display-estimated-range, display-charging-state, display-power
• Charging control (write): set-charging-power, set-charge-limit (Tesla only), charging-mode, boost, phase-mode (if supported), min-max-amperage
• Optimization (write): smart-mode, preferred-operating-mode, solar-optimization (+ sun-share), price-control, target-charging, soc-plan, priority, time-control
• Optional: phase-switching, sleep-mode, location-detection, battery-capacity + consumption (target-charging setup — the vehicle's capacity is not provided by the vendors, the user enters it)
• Onboarding/setup: connect, home-location, connector-type, add-charging-location (VW CCO only)
• Tesla-specific: install-certificate, set-scopes, support-tesla-vehicle-command-protocol

Notes:

• EV charging is fully controllable through capabilities. The typical app-facing charging modes map as follows:
  • Always charge — disable smart-mode: the car behaves as without any optimization (plug in → charge until full or until the charge limit).
  • Surplus charging — enable solar-optimization; add sun-share < 100 for a deliberate grid share.
  • Charge plan / departure time (daily or per-weekday) — target-charging with an SoC or kWh target by executionTime.
  • Price-optimized — price-control with a ct/kWh threshold.
• display-charging-state is the capability to use for the device's charging state.
• add-charging-location (VW CCO): the PUT body is empty ({ }) and only verifies that the end user has set a charging location for the clever-PV charging contract in the vehicle/VW app — it does not set a location and does not use the vehicle's current position. chargingLocationId in the capability's data is read-only and identifies that contract. See Interventions → add-charging-location-required.
• set-charge-limit is the vehicle-wide ceiling (currently only Tesla receives the command); the per-plan “Target SoC” is target-charging's targetSoC and can sit below it.
• Car linked to a clever-PV wallbox. connector-type = cpvWallbox marks the car as charging through a wallbox that clever-PV controls itself (it sets link-to-wallbox to linked: true). Charging control then lives on the wallbox device: enabling target-charging, boost, or on-off on the car is rejected with 500 / errorCode: "carLinkedToWallbox", and time-control schedules written to the car are stored inactive. wallPlug and unknownWallbox do not link. See target-charging details for detection and the wallbox-side setup.

Wallbox

• Typical (read): core, display-charging-state, display-charging-current, display-charging-phases, display-power
• Charging control (write): set-charging-power, charging-mode, boost, phase-mode (if supported), min-max-amperage
• Optimization (write): smart-mode, solar-optimization (+ sun-share), price-control, target-charging (kWh target only — no SoC available), soc-plan, priority, time-control
• Optional: phase-switching, sleep-mode, connect (vendor/ocpp dependent), battery-capacity + consumption (see notes)

Notes:

• Plug-in does not start charging by itself — whether a session starts depends on the charger's authorization setting and on an enabled optimization; see Charging Behaviour After Plug-in.
• A wallbox is functionally the car's twin: the same optimization capabilities apply, with two differences — no SoC (target-charging works with targetWh only), and automatic phase switching (automatic2Phases/automatic3Phases in phase-mode) is a wallbox specialty that cars don't have.
• "Charge as fast as possible right now" is boost: a single enable forces max-amperage / three-phase charging and suspends the smart optimizations until boost is disabled or the car is unplugged. Boost alone is the full sequence — it turns the wallbox on itself, so no on-off write is needed before or after (an on after boost can even undercut the boost amperage), and a vehicle must be plugged in or the enable is accepted but not applied (re-fetch shows enabled: false) — see the capability reference for the full lifecycle and asset-health guidance (frequent boost sessions are fine; rapid on-off/boost toggling loops are what wears the hardware).
• If a car in the home is configured with connector-type: cpvWallbox, its charging plan belongs on the wallbox: target-charging on the wallbox governs whatever vehicle charges there (kWh target only), while the car's own target-charging/boost/on-off writes are rejected with carLinkedToWallbox — see target-charging details.
• For the common "one wallbox, one car" setup, the user can enter the car's battery-capacity (Wh) and consumption (Wh/km) on the wallbox. They are not auto-detected; clever-PV uses them to translate a kWh charging target into an approximate km / percent equivalent in the UI — and both are required before target-charging can be enabled.

Heat pump

• Typical (read): core, display-temperature, display-heating-state
• Optional (read): display-power (only when the vendor/model reports power), pv-control, consumption-overview
• Onboarding/setup: connect, email-verification
• Control (write, when present in capabilities[]): smart-mode (master switch — no optimization runs without it), preferred-operating-mode (monitoring / smartControl), solar-optimization (PV-surplus control, tuned via rated-capacity), and price-optimization (price-optimized running times). Which of these a given model exposes is catalog-driven, so always rely on the device's capabilities[].

Notes:

• Deliberately simplified control surface. Heat pumps expose fewer settings than switches or heating rods: there is no price-control (no user-facing price threshold — price-optimization is a plain on/off and clever-PV plans the cheapest running times internally), and no target-control, time-control, soc-plan, or on-off. There is also no manual mode: the meaningful preferred-operating-mode values are monitoring and smartControl.

• rated-capacity is pre-filled with 2000 W at device creation (a typical heat-pump draw); the user can override it with the unit's real value.

• No raw setpoint or temperature control. clever-PV never writes a target temperature or power value to a heat pump. Every optimization decision (smart, price, target) is translated into a single internal on/off command that maps to an SG-Ready-style state — recommended (encourage the unit to consume now) or normal (hand control back to the unit's own program). SG-Ready states are not addressable directly through the API. Returning to normal is vendor-dependent: some integrations accept an explicit "back to normal" command, others only support the recommended trigger — there the run simply expires on the vendor side and clever-PV cannot cut it short. Never assume that the absence of a clever-PV command means the unit has stopped; read display-heating-state instead.

• What "on" physically does depends on the vendor. clever-PV sends one recommended signal, but each cloud integration translates it differently — do not build on a single physical behaviour:

  • Vaillant — triggers a one-time domestic-hot-water (DHW) overcharge. It is refused while the DHW tank is already at or above its target temperature, or while the vendor reports the overcharge feature as blocked.
  • Bosch/Buderus — switches the configured DHW circuits to Comfort (and back to Auto for normal). This is an operating-mode change on the hot-water circuit, not a one-shot charge.
  • Viessmann — depends on the control mode configured for the device: either a DHW one-time charge, or a genuine SG-Ready smart-grid state (recommendedOperation / normalOperation), which the unit may also apply to space heating.
  • Solvis — sets the heat-source mode, which is not restricted to hot water.

  In every case the signal is a recommendation: the unit may defer or ignore it, e.g. when the tank is already at target. A heat pump can alternatively be driven by an external SG-Ready relay modeled as a switch device.

• boost is not available for heat pumps (car/wallbox only).

• display-heating-state reports { mode, state, type, lastUpdate }: mode is the control regime currently driving the unit (normal = the unit follows its own program, sgReady = clever-PV is currently encouraging consumption via SG-Ready / DHW charge, powerControl = heating rods only), state is idle or running, and type is what the unit produces while running (heating, cooling, warmWater, or null when the vendor doesn't report it). Which type values appear depends on the manufacturer; tolerate unknown values. When state is idle, ignore type — it is the last known value, not a current activity; only show it while state is running.

• display-temperature currently exposes only a single temperature value — the best reading available from the vendor; which sensor it comes from (outdoor, room, tank, …) is vendor-dependent. Per-zone temperatures are planned for the future and will be read-only; ignore them for a first integration. We do not provide temperature curves/time series via the Connect API.

• consumption-overview can display consumption bars for today and yesterday (see the Electric meter section for the typical capability set).

Electric meter

• Typical (read): core, display-grid-power, display-solar-power, display-community-power, consumption-overview
• Setup (write): measurement-purpose (one-time / may be immutable depending on the device)
• Optional: connect (if vendor auth is required)
• Optional (read, when a battery is attached): display-battery-state, display-soc (when the vendor exposes SoC telemetry), battery-capacity
• Optional (write, when a controllable battery is attached): operation-mode to set the battery to normal, idle, forceCharge, or forceDischarge (always read options.supportedModes — not every vendor supports discharge); control-permission to grant clever-PV permission to control the battery (required by some vendors — e.g. SigEnergy, Fronius — before operation-mode writes are accepted); battery-capacity to register the battery's nominal energy capacity (Wh) when the vendor integration does not expose it automatically

Notes:

• Hybrid inverters (a single physical device that combines a grid/PV meter with battery storage) are modeled as a single electricMeter device that additionally exposes the battery-related capabilities listed above. They do not appear as a separate powerStorage device. As always, capabilities[] is the source of truth for which features are actually exposed for a given hybrid inverter (varies by vendor/model).
• Battery operating-mode control (normal / idle / forceCharge / forceDischarge) is exposed as the operation-mode capability on the electric meter the battery is attached to, not on the power storage device itself. Always read options.supportedModes before writing a mode. An optional power setpoint (watts, > 0, only with forceCharge / forceDischarge) may be sent; omitting power is valid and uses the backend/vendor default.
• The battery-related capabilities appear once the battery has been registered on the meter, which happens from live battery telemetry rather than at onboarding. Right after onboarding a storage system they can still be missing from capabilities[]; poll the device until they show up instead of assuming the battery is unsupported.

PowerStorage (battery/storage)

• Currently unused, no devices available. Batteries are exposed through their hybrid inverters as type electricMeter

Switch

• Typical (read): core, display-power
• Typical (write): on-off, plus optimization-related settings (depending on product/setup)

Notes:

• Switch devices can participate in optimizations (e.g., as a SG-Ready relay for heat pumps).
• Some devices are dual-purpose and appear in the device list under both switch and electricMeter — pick the role by which modelId you onboard; the electricMeter variant is metering-only (no on-off). This covers most Shelly metering models and AVM SmartEnergy 200/210. Only Shelly EM/3EM meters additionally require measurement-purpose (gridMeter/pvProduction); choosing pvProduction re-creates the meter as a producing switch that reports PV output but is still not on-off-controllable.

When to use which write capability

Many writable capabilities have overlapping intent (e.g. multiple ways to "turn a wallbox on"). Pick by the user goal:

Rule of thumb: check capabilities[] for the device — if a capability is present, it is the right path. If two seem to overlap, prefer the more specific one (e.g. target-control over on-off when there is an end condition).

Capability Reference

All examples use camelCase JSON. Enums are serialized as strings (e.g., "online", "threePhases").

Note: "GET" means the capability's data object inside GET /v1/users/{userId}/devices/{deviceId} → capabilities[]. There is no per-capability GET endpoint — GET .../devices/{deviceId}/{capability} returns 405 Method Not Allowed; only PUT exists on that route. data in GET can differ depending on the vendor (e.g., telemetry availability). Always apply null-tolerance. Schema names refer to OpenAPI component schemas from the Swagger file.

The list below is the single source of truth for per-capability payload formats and detailed semantics (e.g., units like Watt/Ampere, SoC meaning, edge cases). The category lists above are only illustrative; always rely on capabilities[] returned by the API.

{
  "name": "Device Name",
  "connectivityStatus": "online"
}

{
  "name": "New Device Name"
}

{
  "connectionId": "00000000-0000-0000-0000-000000000000",
  "vendorId": "11111111-1111-1111-1111-111111111111"
}

{
  "type": "oidcProxy",
  "data": {
    "url": "proto://intercepted?code=..."
  }
}

{
  "city": "Munich",
  "postalCode": "80331",
  "street": "Example Street 1",
  "latitude": 48.137154,
  "longitude": 11.576124
}

{
  "city": "Munich",
  "postalCode": "80331",
  "street": "Example Street 1",
  "latitude": 48.137154,
  "longitude": 11.576124
}

{
  "connectorType": "wallPlug",
  "powerMode": "eleven"
}

{
  "chargingLocationId": "vendor-location-id"
}

{}

{
  "url": "https://..."
}

{}

{
  "url": "https://..."
}

{}

{
  "supported": true
}

{
  "consentGiven": false
}

{}

{
  "mode": "smart"
}

{
  "purpose": "gridMeter"
}

{
  "state": "on"
}

{
  "state": "off"
}

{
  "chargingMode": "clever"
}

{
  "chargingMode": "casual"
}

{
  "chargeLimit": 80
}

{
  "desiredAmperage": 10
}

{
  "minAmperage": 6,
  "maxAmperage": 16
}

{
  "phaseMode": "threePhases"
}

{
  "supported": true
}

{
  "supported": true
}

{
  "enabled": true
}

{
  "enabled": true
}

{
  "linked": true
}

{
  "linked": true
}

{
  "latitude": 48.137154,
  "longitude": 11.576124,
  "atHome": true
}

{
  "soc": 52,
  "lastUpdate": "2026-01-30T12:00:00Z"
}

{
  "range": 280
}

{
  "chargingState": "charging"
}

{
  "amperage": 10
}

{
  "phases": 3
}

{
  "power": 3200,
  "lastUpdate": "2026-01-30T12:00:00Z"
}

{
  "temperature": 43.5,
  "lastUpdate": "2026-01-30T12:00:00Z"
}

{
  "mode": "sgReady",
  "state": "running",
  "type": "warmWater",
  "lastUpdate": "2026-01-30T12:00:00Z"
}

{
  "gridPower": -450,
  "lastUpdate": "2026-01-30T12:00:00Z"
}

{
  "solarPower": 1800,
  "lastUpdate": "2026-01-30T12:00:00Z"
}

{
  "communityPower": 120,
  "lastUpdate": "2026-01-30T12:00:00Z"
}

{
  "state": "charging",
  "chargingPower": 1500,
  "lastUpdate": "2026-01-30T12:00:00Z"
}

{
  "mode": "normal"
}

{
  "mode": "forceCharge",
  "power": 3000
}

{
  "state": "allowed"
}

{
  "request": "allow"
}

{
  "batteryCapacity": 10000
}

{
  "batteryCapacity": 10000
}

{
  "consumption": 150
}

{
  "consumption": 150
}

{
  "enabled": false,
  "threshold": 25
}

{
  "enabled": true,
  "threshold": 25
}

{
  "enabled": true
}

{
  "enabled": true
}

{
  "enabled": true,
  "ratedCapacity": 2200,
  "sunShare": 100
}

{
  "enabled": true
}

{
  "enabled": true,
  "priority": 1,
  "ratedCapacity": 2200
}

{
  "enabled": true,
  "reason": "solar"
}

{
  "enabled": true
}

{
  "mode": "smartControl"
}

{
  "mode": "smartControl"
}

{
  "enabled": true,
  "minControlSoc": 20,
  "maxControlSoc": 80
}

{
  "enabled": true,
  "minControlSoc": 20,
  "maxControlSoc": 80
}

{
  "ratedCapacity": 2200
}

{
  "ratedCapacity": 2200
}

{
  "ratedCapacity": 2200,
  "sunShare": 100
}

{
  "sunShare": 50
}

{
  "priority": 1
}

{
  "priority": 1
}

{
  "switchDelayOn": 300,
  "switchDelayOff": 180
}

{
  "switchDelayOn": 300,
  "switchDelayOff": 180
}

{
  "enabled": true,
  "targetControlLock": null,
  "currentRuntime": 1.25,
  "hasReachedTarget": false,
  "lastTargetControl": "2026-08-04T09:35:00Z",
  "startTime": "06:00:00",
  "endTime": "18:00:00",
  "targetRuntime": "02:00:00",
  "startDate": "2026-08-04T04:00:00Z",
  "endDate": "2026-08-04T16:00:00Z",
  "weekDays": [
    "monday",
    "tuesday",
    "wednesday",
    "thursday",
    "friday"
  ],
  "type": "repeat",
  "useSmartChargePlan": true,
  "sendPushNotification": false,
  "enableTargetControlLimit": true
}

{
  "enabled": true,
  "startTime": "06:00:00",
  "endTime": "18:00:00",
  "targetRuntime": "02:00:00",
  "weekDays": [
    "monday",
    "tuesday",
    "wednesday",
    "thursday",
    "friday"
  ],
  "type": "repeat",
  "useSmartChargePlan": true,
  "sendPushNotification": false,
  "enableTargetControlLimit": true
}

{
  "enabled": true,
  "targetControlLock": null,
  "currentRuntime": 0,
  "hasReachedTarget": false,
  "lastTargetControl": null,
  "executionTime": "07:00:00",
  "targetWh": 12000,
  "targetSoC": null,
  "unitType": "kwh",
  "targetDate": "2026-08-07T05:00:00Z",
  "weekDays": [
    "monday",
    "wednesday",
    "friday"
  ],
  "type": "repeat",
  "useSmartChargePlan": true,
  "sendPushNotification": true,
  "enableTargetControlLimit": false,
  "chargedWh": 3500,
  "consumption": 150,
  "batteryCapacity": 60000,
  "currentSoC": 46,
  "socLimit": 80,
  "lastUpdate": null
}

{
  "enabled": true,
  "executionTime": "07:00:00",
  "targetWh": 12000,
  "unitType": "kwh",
  "weekDays": [
    "monday",
    "wednesday",
    "friday"
  ],
  "type": "repeat",
  "useSmartChargePlan": true,
  "sendPushNotification": true,
  "enableTargetControlLimit": true
}

{
  "nextSchedule": {
    "id": "schedule-id",
    "type": "repeat",
    "weekDays": [
      "monday"
    ],
    "executionTime": "02:30:00",
    "action": "turnOn",
    "actionDetails": null,
    "isActive": true,
    "description": "Example",
    "sendPushNotification": false
  },
  "schedules": [
    {
      "id": "schedule-id",
      "type": "repeat",
      "weekDays": [
        "monday"
      ],
      "executionTime": "02:30:00",
      "action": "turnOn",
      "actionDetails": null,
      "isActive": true,
      "description": "Example",
      "sendPushNotification": false
    }
  ]
}

{
  "schedules": [
    {
      "id": "existing-schedule-id",
      "type": "repeat",
      "weekDays": [
        "monday"
      ],
      "executionTime": "09:30:00",
      "action": "turnOff",
      "actionDetails": null,
      "isActive": true,
      "description": "Turn off Monday morning",
      "sendPushNotification": false
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "repeat",
      "weekDays": [
        "tuesday"
      ],
      "executionTime": "10:30:00",
      "action": "socPlanOn",
      "actionDetails": {
        "minSoC": 20,
        "maxSoC": 80
      },
      "isActive": true,
      "description": "SoC plan Tuesday morning",
      "sendPushNotification": false
    }
  ]
}

{ "series": [{ "startTimeUtc": "2026-01-29T00:00:00Z", "endTimeUtc": "2026-01-30T00:00:00Z", "interval": "hourly", "entries": [{ "timestamp": "2026-01-29T00:00:00", "total": 0.12, "solar": 0.05, "price": 0.00, "normal": 0.07 }], "solarHours": 1.5, "priceHours": 0.0, "normalHours": 22.5 } }] }

target-control details

target-control (internally "target times") guarantees a device a minimum runtime inside a daily time window — e.g. "run for 2 hours between 06:00 and 18:00 on weekdays". clever-PV decides when inside the window the device runs; you only define the window, the target runtime, and the repetition.

It appears on switch and heatingRod devices. Cars and wallboxes use the energy-based target-charging capability instead — same concept, but with an energy/SoC target rather than a runtime target. Heat pumps expose price-optimization, a thresholdless on/off façade that drives the same target-times mechanism internally.

How it works

1. You configure a window and a target runtime. startTime/endTime define the daily window and targetRuntime the on-time the device should accumulate inside it — all HH:mm:ss, interpreted in the home's local timezone. type selects a single occurrence (once) or a weekly repetition on weekDays (repeat).
2. The backend derives the concrete occurrence. From the weekdays and window it computes the next startDate/endDate as UTC timestamps. These are returned read-only in GET; you never write them.
3. clever-PV plans the run. With useSmartChargePlan: true (the default) the target runtime is placed into the most favorable slots of the window, using the home's electricity tariff and solar situation. With false the device simply runs from the window start until the target runtime is reached.
4. Runtime is accounted while the device actually runs. currentRuntime (decimal, hours) accumulates while the window is active and the device is on — for a switch while the relay is on, for a heat pump while clever-PV is driving it (see display-heating-state: mode ≠ normal and state = running). lastTargetControl is the timestamp of the last accounting tick — informational only.
5. Target reached. When currentRuntime reaches targetRuntime, hasReachedTarget becomes true and the device is switched off if clever-PV was running it. Without enableTargetControlLimit, other optimizations (solar surplus, price control) may still run the device beyond the target — the target is a minimum, not a cap.
6. End of window. When endDate passes, progress resets (currentRuntime back to 0, hasReachedTarget back to false). A repeat configuration advances startDate/endDate to the next matching weekday; a once configuration automatically flips enabled to false.

enableTargetControlLimit (maximum runtime)

When true, the target runtime becomes a hard cap as well as a minimum: once the target is reached — or outside the planned window — the device is kept off even if solar surplus is available or the electricity price is below the price-control threshold. While the device is locked out, targetControlLock contains the UTC timestamp until which the lock holds (the start of the next window); otherwise it is null. When false, target-control only guarantees the minimum runtime and other optimizations remain free to add runtime.

Write fields (TargetControlCapabilityUpdateData)

PUT is a partial update: enabled is the only required field. Optional fields that are omitted (or null) keep their current value, so you can toggle enabled without resending the configuration.

Read-only status fields (GET only)

Notes:

• Until target-control has been configured once, the optional fields can be null in GET — apply null-tolerance.
• REST responses serialize weekDays and type as camelCase strings ("monday", "repeat"). On the live telemetry stream, target-control payloads are currently forwarded in the platform-internal representation, where these two enums appear as numbers (weekDays: 0 = Sunday … 6 = Saturday; type: 0 = once, 1 = repeat). Handle both if you consume the stream.

target-charging details

Cars linked to a clever-PV wallbox. Setting connector-type to cpvWallbox on a car means the vehicle charges through a wallbox that clever-PV controls itself. Charging control then moves to the wallbox device, so that two devices never steer the same charging session:

• Enabling target-charging on the car ("enabled": true while it is disabled) is rejected with 500 and errorCode: "carLinkedToWallbox". Parameter-only updates on an already enabled plan are not affected. The same rejection applies to boost and on-off on the car; time-control schedules written to the car are accepted but stored inactive.
• wallPlug and unknownWallbox do not link the car — the rule is specific to cpvWallbox.
• Detect it before writing: the link-to-wallbox capability on the car (present when the home has a wallbox) reports linked: true. This is exactly the state the check reads, and it can also be set directly through that capability. connector-type.connectorType == "cpvWallbox" is the usual way the link gets set and works as a secondary indicator. There is currently no intervention for this state, so hide the plan modes on the car based on these fields instead of letting the user run into the error.
• Where the plan goes: PUT /v1/users/{userId}/devices/{wallboxDeviceId}/target-charging on the wallbox. It governs whatever vehicle charges at that wallbox. Use unitType: "kwh" with targetWh only (percent is accepted with 202 but not applied — no SoC is available for planning), and configure battery-capacity and consumption on the wallbox first, otherwise enabling fails with target-charging-setup-required.

Enabling applies in two asynchronous steps. A PUT with "enabled": true on a device that has no plan yet is processed as (1) activate — an initial plan is created with executionTime: "08:00:00", targetWh: 5000, unitType: "kwh", type: "once", weekDays: [] and targetDate = the next 08:00 local time — and (2) apply your parameters on top of it. The gap between the two steps is typically about a second. A GET inside that window returns the initial plan — not your values and not the previous state. Device detail (GET .../devices/{deviceId}) and device list (GET .../devices) read the same state; there is no separate cache, so which one you call makes no difference.

• There is no per-write status, ETag, or completion signal yet, and lastUpdate on target-charging is not populated — don't rely on it.
• Avoid the transitional read: send the plan values first with "enabled": false (they are stored while disabled), then a second PUT with "enabled": true. Activation reuses the stored plan, so no initial plan is created. enabled is required in every PUT.
• Or verify the read-back: compare the re-fetched data against the fields you sent (executionTime, targetWh/targetSoC, unitType, weekDays, type, useSmartChargePlan; targetDate is derived and recomputed) and re-read after 1–2 s if they differ. If the values still haven't converged after a few seconds, contact support with the traceId of the 202 response.

time-control details

PUT uses replace-all semantics: send the full desired list of schedules. Any schedule not included in the request will be deleted.

Schedules fire at executionTime in the home's local timezone. nextSchedule in GET is also computed against the home's local time.

The API validates every schedule in the incoming list before deleting or recreating any existing schedule. If schedule validation fails, the request returns 400 Bad Request and the existing schedule list is left unchanged.

Execution-time grid

executionTime must be an exact point on the five-minute execution grid:

• Use HH:mm:ss between 00:00:00 and 23:55:00, inclusive.
• Minutes must be divisible by 5 (00, 05, 10, …, 55).
• Seconds and fractional seconds must be zero.

Examples: 14:35:00 is valid; 14:37:00, 14:35:12, and 14:37:10 are invalid. An off-grid value returns 400 Bad Request with errorCode: "invalidScheduleExecutionTime" instead of creating a schedule that can never run.

Existing legacy schedules may contain an off-grid time. They can still appear in GET responses, but a replace-all PUT that sends one back unchanged is rejected. Move the time to a five-minute grid point before submitting the full list.

Schedule fields:

Actions & actionDetails per device category:

phaseMode values: singlePhase, twoPhases, threePhases, automatic2Phases, automatic3Phases.

Heat pumps do not have time-control — their optimization runs through price-optimization and solar-optimization instead.

Schedules fire independently of smart-mode: an active schedule executes even while smart-mode is disabled. What deactivates schedules is isActive: false — or a write of preferred-operating-mode monitoring, which deactivates all of them. Note that a scheduled action behaves exactly as if the user had performed it manually at that moment; on the next control cycle the smart optimizations (if enabled) may override its effect — e.g. price control can turn a device back on after a scheduled turnOff.

Schedule validation errors

Schedule-specific failures use the ConnectApiProblemDetails response shape. Handle the stable errorCode; use detail only as a human-readable explanation.

Example off-grid response:

Code
{
  "type": "validationFailed",
  "title": "Invalid Schedule Execution Time",
  "status": 400,
  "detail": "Execution time '14:37:00' is invalid. Schedules are executed on a 5-minute grid: the time must be between 00:00:00 and 23:55:00, minutes must be a multiple of 5 and seconds must be 0 (e.g. 14:35:00).",
  "traceId": "00-...-...",
  "errorCode": "invalidScheduleExecutionTime"
}

Client checklist

• Always evaluate the device's capabilities[] (instead of assumptions per vendor/model).
• Render interventions in the UI (blocker → clear user action).
• Only apply PUT to capabilities you actually see on the device.
• After PUT, reload the device (asynchronous process). A read immediately after the 202 can be transitional — compare data against what you sent and re-read if it differs.
• Evaluate ProblemDetails: type, status, errorCode, traceId.