TL;DR
- One REST API to connect, read and control energy devices from 80+ vendors (wallboxes, cars, heat pumps, inverters, batteries and meters). You build one integration; clever-PV handles the vendor logins and protocols
- Auth: OAuth2 Client Credentials. Every request uses
Bearer {token}and auserIdpath parameter you define - Core flow:
GET /vendors→ connect a vendor account →GET /devices→ read and writecapabilities[] - Capabilities, not device types: never hard-code what a device can do; always check
capabilities[]at runtime - Errors: a stable
errorCodeand atraceIdon every error, see Error Codes - Rate limit: 100 requests per 10 seconds, see Rate limits
- Vendors: most of the vendors in the clever-PV app are available
Start here
Want the vendor login inside your own UI? See the Device Onboarding Flow.
Try it without code
The browser-based Connect API TUI walks through vendors, connections and devices with your API credentials and shows every request and response.
Key Features
- Multi-Vendor Support: Connect devices from multiple vendors through a single, consistent API
- Flexible Authentication: Supports OAuth2/OIDC with PKCE, proxy-based OAuth and form-based vendor logins — or the hosted Connect UI
- Device Management: Discover, link, and manage devices from connected vendors
- Real-time Capabilities: Access device capabilities and data including charging status, location, power consumption, and more
- Live Telemetry: Receive real-time device state updates via Azure Event Hubs for continuous monitoring, dashboards, and analytics
Base URLs
| Purpose | URL |
|---|---|
| Auth | https://auth.clever-pv.com |
| API | https://api.clever-pv.com/connect |
API Versioning
All endpoints are versioned under a /v1/ path prefix (e.g., GET /v1/users/{userId}/devices). Our versioning policy:
- Additions are backwards-compatible within
/v1/— new endpoints, new optional fields on responses, new enum values, and new capabilities can appear at any time without a version bump. Clients must tolerate unknown fields and unknown enum values. - Breaking changes ship behind a new version prefix (e.g.,
/v2/). The/v1/prefix continues to work in parallel during the deprecation window. - Error status codes can be corrected within
/v1/;errorCodeis stable. If an error is returned with an inaccurate HTTP status (e.g. a rejection that came back as500instead of409), the status may be corrected without a version bump. TheerrorCodevalue stays the same, so branch onerrorCode, not on the HTTP status alone (see Error Codes). - Deprecations are announced in this documentation and in the OpenAPI spec via
deprecated: truebefore any endpoint is removed.
When asking an LLM or copilot to write integration code against this API, prefer the current /v1/ patterns documented here over any older snippets you may find.
Rate limits
The Connect API allows 100 requests per 10 seconds (fixed window). For partner tokens (client credentials) the limit is counted per calling IP address: all your API clients and backends that call from the same IP address share one budget.
- All endpoints count towards it. There is no separate limit per endpoint or per capability write.
- When the limit is exceeded, the API returns
429 Too Many Requestswithout a body and without aRetry-Afterheader. Wait for the next 10-second window, then retry with increasing delays. - Cache responses that rarely change — e.g. the vendor catalog (
GET /vendors, connection options) — on your side instead of requesting them per user interaction. - Throttling by a vendor's API is not reported as
429. It arrives as502witherrorCode: "vendorCommunicationError"; retry later with increasing delays (see Error Codes). - The push URL for push meters and the Connect UI pages have their own limits.
All error responses and how to react to them: Error Codes.
Using this documentation with AI tools
Point your coding assistant at /llms.txt for a curated index of every page, or /llms-full.txt for the entire documentation plus the live OpenAPI spec concatenated into a single file — ready to paste into a chat or feed to a RAG pipeline.