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.
• time-control schedule times must be exact five-minute grid points (for example, 14:35:00)
• 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.

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.

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.
• 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.

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)

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
• Typical (write): set-charge-limit, set-charging-power, charging-mode, phase-mode (if supported)
• Optional: min-max-amperage, phase-switching, sleep-mode, location-detection
• Onboarding/setup: connect, home-location, connector-type, (vendor-specific) add-charging-location
• Tesla-specific: install-certificate, set-scopes, support-tesla-vehicle-command-protocol

Notes:

• display-charging-state is the capability to use for the device's charging state.
• set-charge-limit limits the car battery (currently only supported for Tesla).
• “Target SoC” is part of target-charging (TargetChargingCapabilityData.targetSoC).

Wallbox

• Typical (read): core, display-charging-state, display-charging-current, display-charging-phases, display-power
• Typical (write): set-charging-power, phase-mode (if supported)
• Optional: phase-switching, sleep-mode, connect (vendor/ocpp dependent), battery-capacity (when the wallbox reports onboard EV battery info)

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[]): heat-pump optimization is exposed through the same write capabilities as other controllable devices — e.g. smart-mode (master switch), preferred-operating-mode, price-control, target-control, and the PV-surplus tuning settings priority / rated-capacity / switch-delay. Which of these a given model exposes is catalog-driven, so always rely on the device's capabilities[].

Notes:

• 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 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.
• What "on" physically does: for the integrated cloud vendors (Vaillant, Bosch/Buderus, Viessmann, Solvis) the recommended signal triggers a domestic-hot-water (DHW) charge via the vendor cloud — it does not drive the space-heating circuit, and the unit may defer or ignore it (e.g. when the DHW tank is already at its target temperature). 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 the current mode / state / reason (e.g. reason: "solar" or "price") — i.e. which optimization currently drives the unit. Enum values are vendor-dependent; tolerate unknowns.
• display-temperature currently exposes only a single temperature value (expected to be expanded later). 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, or forceCharge; 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) is exposed as the operation-mode capability on the electric meter the battery is attached to, not on the power storage device itself.

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: 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
}

{
  "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"
}

{
  "chargeLimit": 80
}

{
  "desiredAmperage": 10
}

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

{
  "phaseMode": "threePhases"
}

{
  "supported": true
}

{
  "supported": true
}

{
  "enabled": true
}

{
  "enabled": true
}

{
  "linked": true
}

{
  "latitude": 48.137154,
  "longitutde": 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": "heating",
  "state": "running",
  "reason": "solar",
  "type": "heating",
  "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": "idle"
}

{
  "state": "allowed"
}

{
  "request": "allow"
}

{
  "batteryCapacity": 10000
}

{
  "batteryCapacity": 10000
}

{
  "consumption": 150
}

{
  "consumption": 150
}

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

{
  "enabled": true
}

{
  "enabled": true
}

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

{
  "enabled": true
}

{
  "mode": "smartControl"
}

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

{
  "ratedCapacity": 2200
}

{
  "priority": 1
}

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

{
  "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,
  "executionTime": "02:30:00",
  "targetWh": 12000,
  "targetSoC": 80,
  "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 } }] }

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.

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.

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).
• Evaluate ProblemDetails: type, status, errorCode, traceId.