Documentation

Welcome to Clever-PV Connect API

Copy page

TL;DR

• Single REST API for 80+ vendors (most of the vendors already available in the clever-PV app) — you build one integration, we handle the vendor protocols
• Auth: OAuth2 Client Credentials → every request uses Bearer {token} + a userId path param you define
• Core flow: GET /vendors → connect vendor → GET /devices → read/write capabilities[]
• All device interaction happens through capabilities — never hardcode what a device can do, always check capabilities[] at runtime
• Errors carry a stable errorCode and a traceId — see Error Codes. Rate limit: 100 requests per 10 seconds, see Rate limits

The Clever-PV Connect API enables you to integrate and manage devices from various vendors in your applications. Whether you're building a mobile app, web platform, or IoT solution, the Connect API provides a unified interface to connect devices from vendors like Tesla, Viessmann, Vaillant, Solvis, and more.

What is the Connect API?

The Connect API is a RESTful service that enables connecting third-party devices to custom applications. It handles vendor-specific authentication flows, device discovery, and device management, allowing you to focus on building great user experiences rather than managing complex OAuth implementations and vendor-specific protocols.

Key Features

• Multi-Vendor Support: Connect devices from multiple vendors through a single, consistent API
• Flexible Authentication: Supports various authentication methods including OAuth2/OIDC with PKCE, proxy-based OAuth, and form-based authentication
• 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

Getting Started

To get started with the Connect API, follow our comprehensive Device Onboarding Flow guide, which walks you through:

1. Discovering available vendors
2. Understanding connection options for each vendor
3. Connecting the vendor — either via Connect UI, or by implementing the vendor login yourself
4. Creating connections and linking devices
5. Accessing device data and capabilities
6. Setting up Live Telemetry for real-time device data streaming

For the API-level OAuth2 setup (obtaining your Bearer token), see Authentication.

To try the flow by hand before writing code, use the browser-based Connect API TUI — it walks through vendors, connections, and devices interactively and shows every request and response. It requires the API credentials issued by Clever-PV.

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/; errorCode is stable. If an error is returned with an inaccurate HTTP status (e.g. a rejection that came back as 500 instead of 409), the status may be corrected without a version bump. The errorCode value stays the same, so branch on errorCode, not on the HTTP status alone (see Error Codes).
• Deprecations are announced in this documentation and in the OpenAPI spec via deprecated: true before 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 Requests without a body and without a Retry-After header. 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 as 502 with errorCode: "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.