{"id":44566986,"url":"https://github.com/trcyberoptic/hoval-connect-api","last_synced_at":"2026-05-25T23:02:12.403Z","repository":{"id":338331237,"uuid":"1154468140","full_name":"trcyberoptic/hoval-connect-api","owner":"trcyberoptic","description":"Home Assistant integration for Hoval Connect (HACS) — control heating (HK) and ventilation (HV) via the Hoval IoT cloud API","archived":false,"fork":false,"pushed_at":"2026-04-02T22:59:14.000Z","size":281,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-03T09:12:58.668Z","etag":null,"topics":["azure-iot-hub","climate-control","hacs","heating","home-assistant-custom-component","home-automation","homeassistant","hoval","hoval-connect","hvac","iot","smart-home","ventilation"],"latest_commit_sha":null,"homepage":"https://github.com/trcyberoptic/hoval-connect-api#home-assistant-integration","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trcyberoptic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T12:26:43.000Z","updated_at":"2026-04-02T22:59:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/trcyberoptic/hoval-connect-api","commit_stats":null,"previous_names":["trcyberoptic/hoval-connect-api"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/trcyberoptic/hoval-connect-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trcyberoptic%2Fhoval-connect-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trcyberoptic%2Fhoval-connect-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trcyberoptic%2Fhoval-connect-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trcyberoptic%2Fhoval-connect-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trcyberoptic","download_url":"https://codeload.github.com/trcyberoptic/hoval-connect-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trcyberoptic%2Fhoval-connect-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32280981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure-iot-hub","climate-control","hacs","heating","home-assistant-custom-component","home-automation","homeassistant","hoval","hoval-connect","hvac","iot","smart-home","ventilation"],"created_at":"2026-02-14T01:10:26.856Z","updated_at":"2026-05-25T23:02:12.386Z","avatar_url":"https://github.com/trcyberoptic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hoval Connect API – Unofficial Documentation \u0026 Home Assistant Integration\n\nReverse-engineered API documentation for the **Hoval Connect** IoT platform (used by Hoval heating/ventilation systems), plus a **Home Assistant custom integration** (HACS-compatible).\n\n\u003e ⚠️ **Unofficial.** Not affiliated with Hoval. Use at your own risk. API may change without notice.\n\n\u003e **Successor to [Hoval-GatewayV2-CANBUS-MQTT](https://github.com/trcyberoptic/Hoval-GatewayV2-CANBUS-MQTT).** This cloud-based integration requires no additional hardware — just your Hoval Connect credentials. The previous project used CAN bus + MQTT via a physical gateway connection.\n\n## Home Assistant Integration\n\n### Installation (HACS)\n\n1. In HACS, go to **Integrations** → **Custom repositories**\n2. Add `https://github.com/trcyberoptic/hoval-connect-api` as an **Integration**\n3. Install **Hoval Connect**\n4. Restart Home Assistant\n5. Go to **Settings** → **Integrations** → **Add Integration** → search **Hoval Connect**\n6. Enter your Hoval Connect email and password\n\nPlants and circuits are discovered automatically from your account.\n\n### What You Get\n\n**Fan entity** (per HV ventilation circuit):\n- Continuous speed slider: 0–100% (temporary override, keeps time program active)\n- Turn on/off toggle (standby mode)\n- Configurable turn-on mode: resume last program, or activate week1/week2\n- Debounced slider input (1.5s) to prevent API rate-limiting\n\n**Climate entity** (per HK heating circuit):\n- Target temperature control\n- HVAC modes: Heat / Auto / Off (standby)\n- HVAC action reflects actual circuit status\n\n**Program select** (per HV/HK circuit):\n- Switch between week1, week2, eco mode, standby, constant\n- Shows user-defined program names from the Hoval app\n- Current program pre-selected\n\n**Sensor entities** (per circuit, filtered by type):\n- **HV:** Outside temperature, exhaust temperature, air volume, humidity (actual/target), program air volume\n- **HK:** Outside temperature, flow temperature (actual/target), room temperature setpoint\n- **BL:** Heat generator temperature (actual/target), return temperature, operating hours, operating hours \u003e50%, switching cycles, heat produced, electrical energy consumed\n- **WW:** Hot water setpoint, tank temperature top (SF1), tank temperature bottom (SF2)\n- **All:** Operation mode, active week program, active day program\n\n**Plant-level sensors:**\n- Weather condition and forecast temperature\n- Latest event type, message, and timestamp\n- Active event count\n\n**Binary sensors** (per plant):\n- Online/offline (connectivity class)\n- Error status (problem class, detects blocking/locking events)\n\n**Diagnostics:**\n- Full diagnostic data export with automatic PII redaction (tokens, credentials, plant IDs)\n\n**Options** (configurable per integration entry):\n- Turn-on mode: resume / week1 / week2\n- Temporary override duration: until end of current phase (default, v0.15.0+) / 4 hours / until midnight\n- Polling interval (default: 60s)\n\n**Services:**\n- `hoval_connect.reset_temporary_change` — cancel an active temporary override on a HomeVent fan or heating-circuit climate entity, returning control to the underlying time program. Target = the fan or climate entity. Useful in automations that need to end a manual boost cleanly (instead of waiting for the override to expire).\n\n**Under the hood:**\n- 2-step token management (ID token + Plant Access Token) with TTL caching and auto-refresh\n- Skips API calls when plant is offline, invalidates token cache on reconnect\n- Parallel API fetches for circuits, live values, programs, events, and weather\n- Program cache (5min TTL) reduces API calls\n- Dynamic entity discovery — new circuits added without restart\n- All circuit reads use the `/v3` API (Hoval removed `/v1` circuit endpoints in April 2026); legacy v1 enum values still get normalized to v3 keys as a fallback\n- Temporary overrides use the `/v4` API (v0.15.0+) for forward-compatibility; `endOfPhase`/`duration` body shape, reset still on `/v3` DELETE\n\n### Summer-boost Blueprint (optional)\n\nA bundled Home Assistant Blueprint auto-boosts the HomeVent to 90 % on warm\nafternoons when at least one (non-office) room exceeds a comfort threshold AND\nthe outside air is moderate AND cooler than indoors. The boost ends when every\nnon-excluded room drops below a configurable comfort target (default 21 °C),\nwhen the outside air gets too warm, when the time window expires, when the HV\ngoes into standby, or when the user changes the fan slider by hand.\n\nBlueprint source: [`blueprints/automation/trcyberoptic/hoval_hv_summer_boost.yaml`](blueprints/automation/trcyberoptic/hoval_hv_summer_boost.yaml).\n\n**Prerequisites:**\n\n1. Hoval Connect integration **v0.15.1 or later** (ships the\n   `hoval_connect.reset_temporary_change` service used to end the boost\n   cleanly).\n2. Two helpers that persist across HA restarts. Either create them in the UI\n   under **Settings → Devices \u0026 Services → Helpers**, or paste this into\n   `configuration.yaml`:\n\n   ```yaml\n   input_boolean:\n     hoval_hv_boost_active:\n       name: HV Boost aktiv\n       icon: mdi:fan-speed-3\n\n   input_datetime:\n     hoval_hv_boost_started_at:\n       name: HV Boost Startzeit\n       has_date: true\n       has_time: true\n   ```\n\n   Reload YAML configuration (or restart HA).\n\n**Install the Blueprint:**\n\n- *Option A — Import from URL:* In HA, **Settings → Automations \u0026 Scenes →\n  Blueprints → Import Blueprint** and paste the raw URL of the YAML file\n  (the `source_url` inside the file points there).\n- *Option B — Copy the file:* drop the YAML into\n  `\u003cHA_config_dir\u003e/blueprints/automation/trcyberoptic/hoval_hv_summer_boost.yaml`\n  and reload Blueprints from the UI.\n\n**Configure:** **Settings → Automations \u0026 Scenes → Blueprints → Hoval HomeVent\nSommer-Boost → Create Automation**. Pick the HV fan entity, program-select\nentity, outside-temperature sensor, the room sensors that should participate,\nthe office sensor to exclude, the two helpers, and your notify service. The\nthresholds default to 23 °C / 21 °C / 25 °C / 25.5 °C / 15 min / 90 %; adjust\nto taste.\n\n### Known Limitations\n\n- **HV, HK, BL, and WW circuits only.** Solar (SOL), fresh water (FRIWA), and other circuit types are not yet implemented.\n- **BL energy sensors:** Heat produced and electrical energy consumed are in MWh (verified on UltraSource B Compact).\n- **No time program editing.** Time programs can be read but not modified through the integration.\n- **No energy/temperature history.** Historical statistics endpoints are documented but not yet integrated.\n- **No holiday mode control.**\n- **Single account only.** Each HA instance supports one Hoval Connect account.\n\n### Requirements\n\n- A Hoval Connect account (same credentials as the Hoval Connect mobile app)\n- Home Assistant 2024.1.0 or newer\n\n---\n\n## API Documentation\n\n### Overview\n\nHoval Connect is a cloud platform that connects Hoval HVAC systems (heating, ventilation, hot water) via an IoT gateway to Azure IoT Hub. The mobile app (Android/iOS) communicates through a REST API hosted on Azure.\n\n### Architecture\n\n```\nHoval Device ←→ IoT Gateway ←→ Azure IoT Hub ←→ Hoval Core API ←→ Mobile App / HA Integration\n                                                  (REST/JSON)\n```\n\n### Infrastructure\n\n| Component | URL |\n|-----------|-----|\n| **Core API** | `https://azure-iot-prod.hoval.com/core` |\n| **Identity Provider** | SAP Cloud Identity Services (IAS) |\n| **OIDC Discovery** | `https://akwc5scsc.accounts.ondemand.com/.well-known/openid-configuration` |\n| **IoT Hub** | `iot-hub-neu-prod.azure-devices.net` |\n| **Gateway Desk** | `gateway.hovaldesk.com` |\n| **Monitoring** | Grafana Cloud (`logs-prod-012.grafana.net`) |\n\n## Authentication\n\n### Step 1: Get ID Token (OAuth2 Password Grant)\n\n\u003e **Note:** The `client_id` below is the public OAuth2 client ID for the Hoval Connect mobile app, extracted from the official Android/iOS app. It is the same for all users and is required by the SAP IAS identity provider.\n\n```bash\ncurl -X POST \"https://akwc5scsc.accounts.ondemand.com/oauth2/token\" \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"grant_type=password\" \\\n  -d \"client_id=991b54b2-7e67-47ef-81fe-572e21c59899\" \\\n  -d \"username=YOUR_EMAIL\" \\\n  -d \"password=YOUR_PASSWORD\" \\\n  -d \"scope=openid\"\n```\n\n**Response:**\n```json\n{\n  \"access_token\": \"opaque-token...\",\n  \"id_token\": \"eyJhbGci...\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 1800\n}\n```\n\n\u003e **Important:** Use the `id_token` (JWT) as your Bearer token, NOT the `access_token`.\n\n**Token lifetime:** 30 minutes.\n\n**JWT Claims:**\n| Claim | Description |\n|-------|-------------|\n| `sub` | User ID (e.g., `P000001`) |\n| `groups` | `Hoval-IoT-Prod-BasicUser` |\n| `aud` | Array of audience IDs |\n| `app_tid` | Application tenant ID |\n\n### Step 2: Get Plant Access Token\n\nMost plant-specific endpoints require an additional `X-Plant-Access-Token` header.\n\n```bash\ncurl \"https://azure-iot-prod.hoval.com/core/v1/plants/{plantExternalId}/settings\" \\\n  -H \"Authorization: Bearer {id_token}\"\n```\n\n**Response:**\n```json\n{\n  \"token\": \"eyJhbGci...\",\n  \"featureMap\": { \"OP\": \"OWN_PLANT\", \"PE\": \"PROGRAMS_EDIT\", ... },\n  \"plantSetting\": {\n    \"plantExternalId\": \"123456789012345\",\n    \"address\": { \"street\": \"...\", \"city\": \"...\", \"countryCode\": \"CH\" },\n    \"plantName\": \"MyPlant\"\n  },\n  \"isPlantOwner\": true\n}\n```\n\n**Plant Access Token lifetime:** ~15 minutes (JWT with `exp` claim).\n\n### Auth Summary\n\n```\nid_token (30min) → Authorization: Bearer {id_token}\nplant_access_token (15min) → X-Plant-Access-Token: {token}\n```\n\n## API Endpoints\n\n### Base URL\n\n```\nhttps://azure-iot-prod.hoval.com/core\n```\n\n### Notation\n\n- `{plantId}` = Plant External ID (15-digit number, e.g., `123456789012345`)\n- `{circuitPath}` = Circuit path (e.g., `520.50.0`)\n- 🔑 = Requires `Authorization: Bearer {id_token}`\n- 🏭 = Also requires `X-Plant-Access-Token`\n\n---\n\n### Bootstrap \u0026 User\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| POST | `/api/bootstrap` | 🔑 | Environment info + user settings |\n| GET | `/api/my-plants?size=12\u0026page=0` | 🔑 | List user's plants |\n| GET | `/api/user-settings` | 🔑 | User profile |\n| GET | `/api/contracts/active?plantExternalId={plantId}` | 🔑 | Active service contracts |\n\n#### POST `/api/bootstrap`\n```json\n{\n  \"environmentInfo\": {\n    \"environment\": \"prod\",\n    \"solarWebUiBaseUrl\": \"https://helio.sun\"\n  },\n  \"userSetting\": {\n    \"userId\": \"P000001\",\n    \"email\": \"user@example.com\",\n    \"firstName\": \"...\",\n    \"lastName\": \"...\",\n    \"platformFeatures\": [\"REDEEM_PLANT_ACCESS_CODE\"],\n    \"language\": \"DE\",\n    \"availableLanguages\": [\"DE\", \"EN\", \"FR\", \"IT\"]\n  }\n}\n```\n\n#### GET `/api/my-plants`\n```json\n[\n  {\n    \"plantExternalId\": \"123456789012345\",\n    \"description\": \"MyPlant\",\n    \"isOnline\": true,\n    \"isOnboarded\": true,\n    \"isContractValid\": true\n  }\n]\n```\n\n#### GET `/api/contracts/active`\n```json\n[\n  {\n    \"ContractID\": \"0000000000\",\n    \"ContractType\": \"000000000000000000\",\n    \"ValidFrom\": \"2025-01-01\",\n    \"ValidTo\": \"2050-12-30\",\n    \"GatewaySerialID\": \"123456789012345\",\n    \"isOnboarded\": true,\n    \"Latitude\": \"47.000000\",\n    \"Longitude\": \"8.000000\"\n  }\n]\n```\n\n---\n\n### Plant Settings \u0026 Access\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| GET | `/v1/plants/{plantId}/settings` | 🔑 | Plant access token + features + address |\n| GET | `/v1/plant-shares?plantExternalId={plantId}` | 🔑🏭 | Shared access list |\n| GET | `/business/plants/{plantId}/is-online` | 🔑🏭 | Online status (boolean) |\n\n---\n\n### Circuits\n\nCircuits represent the controllable components of a plant (heating, ventilation, hot water, etc.).\n\n#### Circuit Types\n\n| Code | Description |\n|------|-------------|\n| HK | Heating circuit (Heizkreis) |\n| BL | Boiler |\n| WW | Warm water (Warmwasser) |\n| FRIWA | Fresh water station (Frischwasser) |\n| HV | Home ventilation (Lüftung) |\n| SOL | Solar |\n| SOLB | Solar buffer |\n| PS | Pool/Swimming |\n| GW | Gateway |\n\n\u003e **API change (2026-04-21):** Hoval removed every `/v1/plants/{id}/circuits/...` endpoint and now returns `HTTP 404 \"No static resource ...\"`. All circuit reads and writes now use `/v3` (or `/v4` for the newer temporary-change variant). See `docs/openapi-v3.json` for the live spec.\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| GET | `/v3/plants/{plantId}/circuits` | 🔑🏭 | All circuits with overview data |\n| GET | `/v3/plants/{plantId}/circuits/{circuitPath}` | 🔑🏭 | Single circuit detail (limits, schedule, plant time) |\n| GET | `/v3/plants/{plantId}/circuits/{circuitPath}/programs` | 🔑🏭 | Constant / eco / week1 / week2 program definitions |\n| GET,PATCH | `/v3/plants/{plantId}/circuits/{circuitPath}/settings` | 🔑🏭 | Read or rename circuit (`circuitName`) |\n| GET | `/business/plants/{plantId}/circuits` | 🔑🏭 | Circuit paths list (partner only) |\n| GET | `/business/plants/{plantId}/heat-generators` | 🔑🏭 | Heat generator info (partner only) |\n\n#### GET `/v3/plants/{plantId}/circuits`\n```json\n[\n  {\n    \"type\": \"GW\",\n    \"moduleType\": \"GW\",\n    \"path\": \"1153.0.0\",\n    \"name\": null,\n    \"isSelectable\": false,\n    \"selectable\": false,\n    \"hasError\": false,\n    \"activeProgram\": null,\n    \"operationMode\": null,\n    \"targetValue\": 0.0,\n    \"actualValue\": null,\n    \"airQuality\": null,\n    \"manualValue\": null,\n    \"holidayEnd\": null,\n    \"isAdditionalBoiler\": false,\n    \"additionalBoiler\": false,\n    \"week1OrWeek2Active\": false\n  },\n  {\n    \"type\": \"HV\",\n    \"moduleType\": \"HV\",\n    \"path\": \"520.50.0\",\n    \"name\": \"Lüftung\",\n    \"isSelectable\": true,\n    \"selectable\": true,\n    \"activeProgram\": \"week2\",\n    \"activeWeekProgramName\": \"Sommer\",\n    \"activeDayProgramName\": \"Früh+Abend\",\n    \"circuitStatus\": \"active\",\n    \"operationMode\": \"ventilation\",\n    \"targetValue\": 60.0,\n    \"actualValue\": null,\n    \"manualValue\": null,\n    \"airQuality\": {\n      \"isAirQualityGuided\": false,\n      \"hasAirQualitySensor\": false,\n      \"actualRoomAirQuality\": null,\n      \"airQualityGuided\": false\n    },\n    \"holidayEnd\": null,\n    \"isAdditionalBoiler\": false,\n    \"hasError\": false,\n    \"week1OrWeek2Active\": true\n  }\n]\n```\n\n`activeProgram` enum: `constant`, `ecoMode`, `standby`, `week1`, `week2`, `manual`, `externalConstant`. `targetValue` is the percentage for HV and degrees Celsius for HK.\n\n#### GET `/v3/plants/{plantId}/circuits/{circuitPath}`\n```json\n{\n  \"week1Name\": \"Winter\",\n  \"week2Name\": \"Sommer\",\n  \"plantTime\": \"2026-04-26T00:10:53+02:00\",\n  \"constantValue\": 50.0,\n  \"ecoModeValue\": 60.0,\n  \"activeProgramConfiguration\": {\n    \"baseValue\": 40.0,\n    \"phases\": [\n      { \"phaseValue\": 60.0, \"start\": {\"hours\": 0, \"minutes\": 0}, \"end\": {\"hours\": 9, \"minutes\": 0} },\n      { \"phaseValue\": 40.0, \"start\": {\"hours\": 9, \"minutes\": 0}, \"end\": {\"hours\": 19, \"minutes\": 0} },\n      { \"phaseValue\": 60.0, \"start\": {\"hours\": 19, \"minutes\": 0}, \"end\": {\"hours\": 24, \"minutes\": 0} }\n    ],\n    \"limits\": null\n  },\n  \"temporaryChangeLimits\": { \"max\": 100.0, \"min\": 15.0, \"step\": 1.0 }\n}\n```\n\n#### Circuit Control Endpoints\n\n\u003e **Note:** Control endpoints return **HTTP 204 No Content** on success (no response body).\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| POST | `/v3/plants/{plantId}/circuits/{circuitPath}/temporary-change` | 🔑🏭 | Legacy variant (operationId `activateTemporaryChange_1`). JSON body: `{\"value\": \u003cfloat\u003e, \"duration\": \"fourHours\"\\|\"midnight\"}` |\n| DELETE | `/v3/plants/{plantId}/circuits/{circuitPath}/temporary-change` | 🔑🏭 | Cancel active temporary override (no v4 equivalent) |\n| POST | `/v4/plants/{plantId}/circuits/{circuitPath}/temporary-change` | 🔑🏭 | Current variant (used by integration v0.15.0+ and Hoval Connect Android app). JSON body: `{\"type\": \"endOfPhase\"\\|\"duration\", \"value\": \u003cfloat\u003e, \"duration\": \u003cminutes\u003e\\|null}` — `duration` in **minutes**, accepted range 30..1440 |\n| POST | `/v3/plants/{plantId}/circuits/{circuitPath}/programs/{program}` | 🔑🏭 | Activate program. `{program}` ∈ `constant`, `ecoMode`, `standby`, `week1`, `week2`, `manual`, `externalConstant` |\n| POST | `/v3/plants/{plantId}/circuits/{circuitPath}/air-quality-guided` | 🔑🏭 | Toggle air-quality-guided mode (HV only, requires sensor) |\n| POST | `/v3/plants/{plantId}/circuits/{circuitPath}/semi-automatic-cooling` | 🔑🏭 | Toggle semi-automatic cooling |\n| POST,DELETE | `/v2/api/holiday/{plantId}` | 🔑🏭 | Activate/cancel holiday mode for selected circuits |\n\nMode-specific `/v1/.../{constant\\|cooling\\|standby\\|manual\\|reset\\|time-programs}` endpoints have all been removed; use `programs/{program}` instead. The old `temporary-change/reset` POST has been replaced by `DELETE /v3/.../temporary-change`.\n\n---\n\n### Live Data \u0026 Statistics\n\n| Method | Path | Auth | Parameters | Description |\n|--------|------|------|------------|-------------|\n| GET | `/v3/api/statistics/live-values/{plantId}` | 🔑🏭 | `circuitPath`, `circuitType` | **Live sensor values** |\n| GET | `/v2/api/statistics/live-values/{plantId}` | 🔑🏭 | `circuitPath`, `circuitType` | Live values (v2) |\n| GET | `/v3/api/statistics/temperature/{plantId}` | 🔑🏭 | `circuitPath`, `circuitType`, `interval` (24h\\|3d), `datapoints` | Temperature history |\n| GET | `/v2/api/statistics/total-energy/{plantId}` | 🔑🏭 | `circuitPath`, `interval` (7d\\|1M\\|1y\\|7y), `granularity` (1d\\|1w\\|1M\\|1y) | Energy consumption |\n| GET | `/v2/api/statistics/heat-consumption/{plantId}` | 🔑🏭 | `circuitPath`, `interval` | Heat consumption |\n| GET | `/v2/api/statistics/solar-yield/{plantId}` | 🔑🏭 | `circuitPath`, `interval` | Solar yield |\n| GET | `/api/telemetry-data/snapshots/live/{plantId}` | 🔑🏭 | `dataPoints` (array) | Raw telemetry snapshots |\n\n#### GET `/v3/api/statistics/live-values/{plantId}`\n\n**Parameters:**\n- `circuitPath` (required): e.g., `520.50.0`\n- `circuitType` (required): `HK`, `BL`, `WW`, `FRIWA`, `HV`, `SOL`, `SOLB`, `PS`, `GW`\n\n**Response (HV circuit):**\n```json\n[\n  { \"key\": \"outsideTemperature\", \"value\": \"5.5\" },\n  { \"key\": \"airVolume\", \"value\": \"40\" },\n  { \"key\": \"humidityTarget\", \"value\": \"50\" },\n  { \"key\": \"humidityActual\", \"value\": \"42\" },\n  { \"key\": \"exhaustTemp\", \"value\": \"22.4\" }\n]\n```\n\n---\n\n### Weather\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| GET | `/v2/api/weather/forecast/{plantId}` | 🔑🏭 | 4-day weather forecast for plant location |\n\n```json\n[\n  {\n    \"_time\": \"2026-02-10T00:00:00Z\",\n    \"weatherCode\": 3,\n    \"weatherType\": \"partialCloud\",\n    \"outsideTemperatureMin\": 4,\n    \"outsideTemperature\": 6\n  }\n]\n```\n\n---\n\n### Events \u0026 Notifications\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| GET | `/v1/plant-events/{plantId}` | 🔑 | Plant error events |\n| GET | `/v1/plant-events/latest/{plantId}` | 🔑 | Latest event |\n| GET | `/v1/plants/{plantId}/notifications` | 🔑🏭 | Notification settings |\n| GET | `/business/notifications` | 🔑🏭 | Business notifications |\n\n#### GET `/v1/plants/{plantId}/notifications`\n```json\n[\n  {\n    \"language\": \"DE\",\n    \"eventTypes\": [\"offline\", \"blocking\", \"warning\", \"info\", \"locking\"],\n    \"id\": \"xxxxxxxx-...\",\n    \"plantExternalId\": \"123456789012345\",\n    \"userId\": \"P000001\",\n    \"email\": \"user@example.com\"\n  }\n]\n```\n\n---\n\n### Gateway \u0026 Software\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| GET | `/api/gateway-software/{plantId}/versions/current` | 🔑🏭 | Current gateway SW version |\n\n---\n\n### Holiday\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| PUT | `/v2/api/holiday/{plantId}` | 🔑🏭 | Set/update holiday mode |\n\n---\n\n### Energy Manager (PV Smart)\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| GET | `/v2/api/energy-manager-pv-smart/available/{plantId}` | 🔑🏭 | PV smart availability |\n| GET | `/v2/api/energy-manager-pv-smart/live/{plantId}` | 🔑🏭 | PV live data |\n| GET | `/v2/api/energy-manager-pv-smart/chart-data/{plantId}` | 🔑🏭 | PV chart data |\n\n---\n\n### Plant Registration\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| POST | `/v1/plant-registrations` | 🔑 | Register a new plant |\n\n---\n\n### News\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| GET | `/v1/news/latest` | 🔑 | Latest news (requires `Hovalconnect-Frontend-App-Version` header) |\n\n---\n\n### OpenAPI Spec\n\nThe full OpenAPI 3.1 specification is available at:\n```\nGET /v3/api-docs\n```\n(~450KB JSON, requires Bearer auth)\n\n## Feature Map\n\nThe plant access token response includes a feature map indicating what operations are available:\n\n| Code | Feature |\n|------|---------|\n| OP | Own Plant |\n| PA | Plant Access |\n| PE | Programs Edit |\n| GSV | Gateway Software View |\n| GSU | Gateway Software Update |\n| GSD | Gateway Software Downgrade |\n| SP | Share Plant |\n| DM | Diagnosis Mode |\n| PT | Parameter Tree |\n| PVV | Plant Visualisation View |\n| PVE | Plant Visualisation Edit |\n| MUV | Meters Unassigned View |\n| MUNE | Meters Unassigned Name Edit |\n| EAS | Energy Accounting Share |\n| PAE | Plant Address Edit |\n| PNE | Plant Name Edit |\n| PAV | Plant Address View |\n| NVR | Notification View Receivers |\n| NMR | Notification Manage Receivers |\n\n## Rate Limits \u0026 Notes\n\n- Token lifetime: 30 min (id_token), ~15 min (plant access token)\n- No documented rate limits, but be respectful\n- The API may lock out accounts after repeated failed auth attempts\n- Some endpoints are partner/business-only (403 for regular users)\n- `business/` endpoints may require elevated access roles\n\n## Disclaimer\n\nThis documentation was created through API analysis and is not officially supported by Hoval. The API may change at any time. Use responsibly and respect Hoval's terms of service.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrcyberoptic%2Fhoval-connect-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrcyberoptic%2Fhoval-connect-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrcyberoptic%2Fhoval-connect-api/lists"}