# Clever-PV Connect API

> B2B REST API for connecting, controlling, and reading energy devices from
> 30+ vendors (Tesla, Viessmann, Vaillant, Solvis, Home Connect, Volkswagen,
> Shelly, OCPP wallboxes, and more) through a single, vendor-neutral interface.
> Authentication is OAuth2 Client Credentials; every request carries a
> `Bearer` token plus a partner-defined `userId` path parameter. The device
> model is **capability-based**: clients always discover what a device can do
> at runtime by reading the `capabilities[]` array, never by hard-coding a
> per-vendor feature matrix.

## Docs

- [Introduction](/introduction): What the Connect API is, key features, base URLs, versioning policy
- [Users and Homes](/users-and-homes): Partner-defined `userId` model, home hierarchy, request scoping
- [Device Onboarding Flow](/device-onboarding-flow): End-to-end flow to link a device — list vendors, run the appropriate auth flow (`oidcProxy` / `oidc` / `ocpp` / `form`), create a connection, link the device
- [Device Capabilities](/device-capabilities): Capability model, read/write semantics, blocked vs. unsupported, per-device-category capability sets, decision table for overlapping write capabilities, full per-capability payload reference
- [Live Telemetry](/live-telemetry): Real-time device updates via Azure Event Hubs, consumer-group setup, message schema, SDK examples (C#, Python, JavaScript)
- [Historical Energy Data](/historical-energy-data): Daily/monthly/yearly consumption and production endpoints, time-series retrieval, base URL
- [Interventions](/interventions): Reference of all `interventions[]` blocker IDs, when each appears, and how to resolve it
- [Surplus Charging Control](/surplus-charging-control): Main-device selection, surplus-charging strategy, control semantics
- [Electricity Tariffs](/electricity-tariffs): Fixed, dynamic and feed-in tariff configuration incl. time-of-use grid fees
- [Energy Prices](/energy-prices): Raw EPEX spot prices per time slot (`stockPrice` in ct/kWh), 3-day window, hourly/quarterHourly resolution
- [Shelly Onboarding](/shelly-onboarding): Vendor-specific `form` flow including the Shelly integrator authorization step and `measurement-purpose` requirement
- [OCPP Wallbox Onboarding](/ocpp-wallbox-onboarding): OCPP wallbox integration walkthrough

## API

- [OpenAPI 3.0.4 Spec (live)](https://api.clever-pv.com/connect/swagger/v1/swagger.json): Machine-readable contract for all endpoints
- [Swagger UI (live)](https://api.clever-pv.com/connect/swagger/index.html): Interactive API reference
- [Authentication](/api-authentication): OAuth2 Client Credentials flow, token endpoint, scope, Bearer-token usage

## Optional

- [API Credentials Setup](/api-credentials-setup): Interactive in-browser tool to test partner credentials and obtain a Bearer token
- [Full documentation bundle](/llms-full.txt): All documentation pages concatenated into a single Markdown file for one-shot LLM ingestion (build-generated)