Release Notes

This section documents changes made to the Partner API.

2026-05-05 - v1.35

• Added new data points to the webhook notifications:
  • hvac.cascade.hs{heatSourceId}.compressor.currentSpeed
  • hvac.cascade.hs{heatSourceId}.emon.compressor.operationStatus
  • hvac.cascade.hs{heatSourceId}.emon.compressor.powerCurrent

2026-04-21 - v1.34

• Added new appliance type CASCADE and respective response schema example in GET /hvacs/{gatewayId}/components endpoint.

2026-04-15 - v1.33

• Changed Gateway Management Portal (GMP) links' query parameter name from state to sessionId.
  • Adapted documentation in the Contracts Management page accordingly.

2026-03-23 - v1.32

• Added new endpoints to manage gateway contracts:
  • PATCH /contracts/{gatewayId} endpoint to accept, reject or revoke a contract.
  • DELETE /contracts/{gatewayId} to acknowledge a contract closed by the end user.
  • For more details, see documentation.

2026-02-26 - v1.31

• Similarly to GET /contracts, GET /contracts/{gatewayId} now returns contract information for all statuses, not just ACTIVE.

2026-02-24 - v1.30

• Auto-acceptance of end-customer-initiated contracts is now possible. For more details, see preconditions.
• Updated limitations of hvac.emon.compressor.powerCurrent in data points.
• Clarified dependencies between DHW setpoints for PATCH /hvacs/{gatewayId}/dhwCircuits/{circuitId}.

2026-02-19 - v1.29

• Added new optional serialNumber field to GET /hvacs/{gatewayId}/components for every component type if available.
• Updated compatibility page with new Bosch and Buderus heat pump portfolio.

2026-01-27 - v1.28

• Improved rate limit mechanism to allow more requests. More specifically, the circuitId and timeProgramId path parameters will be also included in the algorithm. See rate limit for more details.

2026-01-07 - v1.27

• Improved REST API support for ICOM gateway types:
  • GET /hvacs/{gatewayId}/dhwCircuits/{circuitId}/charge endpoint returns available data
  • GET /hvacs/{gatewayId}/heatingCircuits/{circuitId} endpoint returns available data
  • PATCH /hvacs/{gatewayId}/heatingCircuits/{circuitId} endpoint can now be used
  • See limitations for details

2025-12-09 - v1.26

• Improved REST API support for ICOM gateway types:
  • GET /hvacs/{gatewayId}/dhwCircuits/{circuitId} endpoint returns available data
  • GET /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatCurve endpoint returns available data
  • See limitations for details

2025-11-27 - v1.25

• Added new endpoint POST /webhooks/simulation to test webhook integrations by simulating events.
• Updated compatibility page to clarify supported products.

2025-11-19 - v1.24

• Enabled interactive API testing directly in the API Reference (see Try It Out guide).
• Added new data points to the webhook notifications:
  • hvac.compressor.currentSpeed
  • hvac.domesticHotWater.dhw1.chargeStatus
  • hvac.domesticHotWater.dhwX.requestedLevel
  • hvac.heatingCircuit.hcX.flowTemperature
  • hvac.heatingCircuit.hcX.roomTemperature
  • hvac.system.sensor.t0
  • hvac.system.sensor.tc0
  • hvac.system.sensor.tc1

2025-11-13 - v1.23

• Added new partner-initiated gateway onboarding flow via redirect (see preconditions for details).

2025-10-07 - v1.22

• Added a specific rate limiting for the following endpoints:
  • PUT /hvacs/{gatewayId}/dhwCircuits/{circuitId}/timePrograms/{timeProgramId}
  • PUT /hvacs/{gatewayId}/heatingCircuits/{circuitId}/timePrograms/{timeProgramId}
• Improved preconditions documentation about the ways a partner company can get access to an heating appliance.

2025-09-29 - v1.21

• Added support for multiple webhook endpoints per company (previously limited to one).
• Added three new daily aggregate properties:
  • hvac.compressor.domesticHotWater.numberOfStarts
  • hvac.compressor.cooling.numberOfStarts
  • hvac.compressor.pool.numberOfStarts
• Introduction of event type CONTRACT_STATUS which is distributed via webhook notifications:
  • Added ContractStatusEvent to the OpenAPI specification.
  • Extended the Event types documentation to include the new webhook event.
• Extended the GET /contracts/{gatewayId} endpoint with the optional partnerUserId property.

2025-09-10 - v1.20

• Intelligent Single Room Control (ISRC) control type is now considered in:
  • PATCH /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatCurve endpoint.
  • GET /hvacs/{gatewayId}/heatingCircuits/{circuitId} endpoint response.
  • PATCH /hvacs/{gatewayId}/heatingCircuits/{circuitId} endpoint request.
• Extended Heat Curve documentation with information about the different control types that affect the heat curve.
• Marked manualModeSettings, autoModeSettings, and currentSetPointTemperature as optional in GET /hvacs/{gatewayId}/heatingCircuits/{circuitId} endpoint response. This change was needed to support ISRC control types and fixes 404 errors when heating circuit resources are not available from the gateway.

2025-08-21 - v1.19

• Updated rate limiting to consider gatewayId in the request path.
• Added new data point hvac.energyManagement.operationStatus to the webhook notifications.
• Removed deprecated fields:
  • currentSetPointTemperature from GET /hvacs/{gatewayId}/dhwCircuits/{circuitId} endpoint response.
  • firmwareVersion from GATEWAY component type in GET /components endpoint response.

2025-08-07 - v1.18

• Bug fix for the new GET /contracts/{gatewayId} endpoint which was not available for gateways with no consent flag.

2025-07-31 - v1.17

• Updated GET /components endpoint response.
  • Added new field softwareVersion to every component type.
  • Deprecated the firmwareVersion field in the GATEWAY component type; the new softwareVersion field should be used instead.
• Added new endpoint GET /contracts to get all the contracts for the Partner.
• Added new endpoint GET /contracts/{gatewayId} to get the contract information for a specific appliance.
  • This endpoint is the same as the GET /hvacs/{gatewayId}/contract endpoint, but with a different path.
  • The response was extended with new fields: gatewayId, status and statusDate - both in the new and the old endpoints.
  • The GET /hvacs/{gatewayId}/contract endpoint was deprecated.
• Added new endpoint POST /components to perform a system detection via Partner API.

2025-06-12 - v1.16

• New endpoint to create a new API key, given a valid one:
  • POST /api-keys
  • More info about the API key renewal process can be found here
• New endpoint to validate an API key:
  • GET /api-keys/me
• New endpoint to delete an API key:
  • DELETE /api-keys/{keyId}
  • More info about the API key removal process can be found here
• New endpoint to get all stored API keys:
  • GET /api-keys

2025-05-28 - v1.15

• Changed endpoint name, response property and mentions of heatingType to heatingDistributionType:
  • GET /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatingDistributionType
  • Updated limitations section accordingly.

2025-05-21 - v1.14

• Deleted the domain model.
• Fixed the wrong type of faultClass and causeCode in the OAS from string to integer.
• Removed deprecated endpoints:
  • GET /hvacs/{gatewayId}/dhwCircuits/{circuitId}/operationMode
  • PUT /hvacs/{gatewayId}/dhwCircuits/{circuitId}/operationMode
  • Important note: these endpoints are no longer being used. The operation mode can be read/set by using the following endpoints:
    • GET /hvacs/{gatewayId}/dhwCircuits/{circuitId}
    • PATCH /hvacs/{gatewayId}/dhwCircuits/{circuitId}
• Correction on GET /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatCurve endpoint response:
  • Changed the unit of measure of the property roomInfluenceTemperature from Celsius to Kelvin.
• Added new endpoint to get the heating distribution type:
  • GET /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatingType
• Added rate limit to all endpoints in the API.
  • Find more information about the rate limit here.
  • Added a new header, x-ratelimit-remaining, as part of the API responses. This header indicates the number of requests the client can still do before reaching the rate limit. Please check the OpenAPI specification for more details.
• Extended the GET /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatCurve and PATCH /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatCurve endpoints:
  • Added new field controlType.
• Added a new component type, POOLMODULE, to the GET /components endpoint response.

2025-04-22 - v1.13

• Updated information about the expiration of the API Key.
• Implemented a global rate limit across the whole API.

2025-04-14 - v1.12

• Updated the mapping of hvac.emon.compressor.operationStatus and hvac.emon.eheater.operationStatus from OFFLINE to IDLE to reflect that the system is still online.
• Added new PATCH /hvacs/{gatewayId}/dhwCircuits/{circuitId} endpoint that allows to update properties of a specific domestic hot water circuit.
• Deprecated endpoints:
  • GET /hvacs/{gatewayId}/dhwCircuits/{circuitId}/operationMode.
  • PUT /hvacs/{gatewayId}/dhwCircuits/{circuitId}/operationMode.

2025-04-01 - v1.11

• Reverted the data point threshold values to previous values, to allow for more data granularity:
  • hvac.emon.energyConsumptionTotal: from 0.5 kWh to 0.1 kWh
  • hvac.emon.energySupplyTotal: from 0.5 kWh to 0.1 kWh
  • hvac.emon.compressor.energyConsumptionTotal.centralHeating: from 0.5 kWh to 0.1 kWh
  • hvac.emon.compressor.powerCurrent: from 500 W to 100 W
  • hvac.domesticHotWater.dhw1.cylinderTemperature: this was kept unchanged.

2025-03-25 - v1.10

• Added a new documentation section about Heat Curve.
• Increased the data point threshold values to reduce the number of events being pushed:
  • hvac.emon.energyConsumptionTotal: from 0.1 kWh to 0.5 kWh
  • hvac.emon.energySupplyTotal: from 0.1 kWh to 0.5 kWh
  • hvac.emon.compressor.energyConsumptionTotal.centralHeating: from 0.1 kWh to 0.5 kWh
  • hvac.emon.compressor.powerCurrent: from 100 W to 500 W
  • hvac.domesticHotWater.dhw1.cylinderTemperature: from 0.5 °C to 1 °C

2025-03-12 - v1.9

• Added new data point hvac.system.holidayMode.{holidayModeId} to the webhook notifications.
• Added new endpoints to get and update the system date time:
  • GET /hvacs/{gatewayId}/system/dateTime
  • PUT /hvacs/{gatewayId}/system/dateTime
  • Updated the domain model and limitations accordingly.
• Extended the GET /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatCurve and PATCH /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatCurve with new fields.

2025-02-24 - v1.8

• New hvac.domesticHotWater.dhw1.cylinderTemperature data point added. For more information check out the data points page.
• Added new endpoints to get, create and delete the holiday mode of an appliance:
  • GET /hvacs/{gatewayId}/system/holidayModes
  • POST /hvacs/{gatewayId}/system/holidayModes
  • DELETE /hvacs/{gatewayId}/system/holidayModes/{holidayModeId}
  • Updated the domain model and limitations accordingly.

2025-02-11 - v1.7

• Moved the x-api-key header to the security scheme level in the OpenAPI specification for improved visualization of the endpoint protection.
• Added a new field, operationMode, inside the autoModeSettings property in the GET /hvacs/{gatewayId}/dhwCircuits/{circuitId} endpoint.
  • Updated the domain model.

2025-01-22 - v1.6

• Added a new section Remote Maintenance in features overview page.
• OpenAPI specification has been updated reflecting which endpoints are part of the Remote Maintenance features.
• Extended and updated use cases limitations page.
• Improving PATCH /hvacs/{gatewayId}/heatingCircuits/{circuitId}, PUT /hvacs/{gatewayId}/heatingCircuits/{circuitId}/timePrograms/{timeProgramId}, PUT /hvacs/{gatewayId}/dhwCircuits/{circuitId}/timePrograms/{timeProgramId} and PUT /hvacs/{gatewayId}/dhwCircuits/{circuitId}/operationMode documentation.

2025-01-09 - v1.5

• Added new data points for CU-HP control unit to the webhook notifications:
  • hvac.emon.energyConsumptionTotal.lowRes
  • hvac.emon.compressor.energyConsumptionTotal.centralHeating.lowRes
  • hvac.emon.compressor.energyConsumptionTotal.domesticHotWater.lowRes
  • hvac.emon.compressor.energyConsumptionTotal.cooling.lowRes
  • hvac.emon.eheater.energyConsumptionTotal.centralHeating.lowRes
  • hvac.emon.eheater.energyConsumptionTotal.domesticHotWater.lowRes
• Added new data point for xCU-HP control unit to the webhook notifications:
  • hvac.emon.energySupplyTotal
• Adapt data points control unit type documentation:
  • hvac.emon.energySupplyTotal.lowRes
  • hvac.emon.compressor.operationStatus
  • hvac.emon.eheater.operationStatus
• Added new daily aggregate properties as described in the respective documentation

2024-12-20 - v1.4

• Added new data point hvac.system.outdoorTemperature to the webhook notifications.
• Extended data point table with resolution and change threshold columns.

2024-12-16 - v1.3

• Introduction of event type DAILY_AGGREGATE properties which is distributed via webhook notifications:
  • hvac.compressor.centralHeating.numberOfStarts
  • hvac.centralHeating.waterPressure.min
  • hvac.centralHeating.waterPressure.max
  • hvac.centralHeating.waterPressure.mean

2024-12-03 - v1.2

• Improved the description of the API Versioning section.
• Changed the error response message returned with status code 401 in case an invalid API key is provided with a request: the generic standard message "Unauthorized" is now returned instead of the message "Invalid apiKey".

2024-11-21 - v1.1

• Updated description of currentSetPointTemperature in GET /hvacs/{gatewayId}/dhwCircuits/{circuitId} to include the impact of additional features in the data received.
• Added new endpoints to get and update the heat curve settings of a heating circuit:
  • GET /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatCurve
  • PATCH /hvacs/{gatewayId}/heatingCircuits/{circuitId}/heatCurve
  • Updated the domain model and limitations accordingly.
• Added new endpoints to get and update the silent mode of a heat pump system:
  • GET /hvacs/{gatewayId}/system/silentMode
  • PATCH /hvacs/{gatewayId}/system/silentMode
  • Updated the domain model and limitations accordingly.

2024-11-06 - v1.0

• Added new data point hvac.emon.energySupplyTotal.lowRes to the webhook notifications and adapted the list about the limitation based on the control units and data points and linked this page on the Limitations.
• Extended the Event types documentation to include the behavior of appliance resets.
• A breaking change was introduced to the GET /hvacs/{gatewayId}/dhwCircuits endpoint:
  • Instead of returning the setPointTemperature for each mode (except the auto mode), the response now contains the startSetPointTemperature and stopSetPointTemperature which define the range in which the heat pump starts and stops heating the domestic hot water.
  • The offModeSettings object was removed from the response as it's not possible to configure a temperature value for this mode.
  • The domain model was updated accordingly.
• Adapt the release notes structure to include the release date and api version.
• Renamed and expanded the documentation for breaking changes in the API Versioning section.
• Updated the versioning information in the API Reference accordingly.
• Resolved an issue in the endpoint GET /hvacs/{gatewayId}/heatingCircuits/{circuitId}, that was making the API to return an HTTP 404 error for certain appliance configurations.

2024-10-10

• Extended the documentation of the processing of events with information on the effects of downtimes and the effects of slow event processing.
• Added new endpoints to get the list of existing circuits:
  • GET /hvacs/{gatewayId}/heatingCircuits
  • GET /hvacs/{gatewayId}/dhwCircuits
  • Updated the domain model accordingly.
  • Updated the circuitId parameter description for remote control endpoints to indicate where to find available DHW and Heating Circuit ids.
• Added Rate Limiting mechanism for PATCH /hvacs/{gatewayId}/dhwCircuits/{circuitId}/charge.
  • PATCH /hvacs/{gatewayId}/dhwCircuits/{circuitId}/charge was updated including the new rate limiting information.
  • Rate Limiting documentation was added accordingly.

2024-09-26

• Added new endpoints to get and set the time program for heating circuits:
  • GET /hvacs/{gatewayId}/heatingCircuits/{circuitId}/timePrograms/{timeProgramId}
  • PUT /hvacs/{gatewayId}/heatingCircuits/{circuitId}/timePrograms/{timeProgramId}
  • Updated the domain model accordingly.
  • Updated the known use cases limitations accordingly.
• Added autoModeSettings to get and set the selected time program id and the corresponding levels for heating circuits:
  • GET /hvacs/{gatewayId}/heatingCircuits/{circuitId}
  • PATCH /hvacs/{gatewayId}/heatingCircuits/{circuitId}
• Corrected links from the API Reference to the Documentation.

2024-09-09

• Added missing HTTP status code 400 in case of an invalid gatewayId to the API reference.
• Updated GET /components endpoint to return HTTP status code 504 in case of a gateway being offline.
• Added missing HTTP status code 504 in case of a gateway being offline to the API reference to all remote control endpoints.
• Added new endpoints to get and set the time program for domestic hot water circuits:
  • GET /hvacs/{gatewayId}/dhwCircuits/{circuitId}/timePrograms/{timeProgramId}
  • PUT /hvacs/{gatewayId}/dhwCircuits/{circuitId}/timePrograms/{timeProgramId}
• Extended the domain model with TimeProgram and SwitchPoint related to time programs.
• Simplified documentation about known use cases limitations which makes it easier to understand.
• Fixed erroneous schemas in the API reference:
  • Removed the duplicated setPointTemperature field in ManualModeSettings.
  • Removed the nested setPointTemperature field in currentSetPointTemperature.
• Fixed the Download OAS button in the API reference to support all browsers.

2024-08-29

• Added new GET /hvacs/{gatewayId}/dhwCircuits/{circuitId} endpoint that provides details about a specific domestic hot water circuit for a specific appliance.
  • operationMode added to the response because we intend to deprecate GET /hvacs/{gatewayId}/dhwCircuits/{circuitId}/operationMode endpoint in the near future.
• Extended the domain model with the DomesticHotWaterCircuit and DhwModeSettings objects.
• Updated documentation about known use cases limitations which is available here.
• GET /hvacs/{gatewayId}/heatingCircuits/{circuitId} endpoint has been extended with a new object called overridingModes. Its purpose is to report the status of each mode so that it's possible to identify which special mode is overriding the current operation mode of the heating circuit.
• The domain model was extended with OverridingModes object.
• Added a new documentation section about the behaviour and dependencies of overriding modes.
• Updated all remote control endpoints to return HTTP 451 instead of HTTP 428 in case of an outdated consent
  • The Preconditions section was revised accordingly.
  • The OAS of the remote control endpoints was refreshed to reflect the new status code.
• Added new term to the glossary section.

2024-07-30

• Added a description of the new remote control features.
• Added the new GET /hvacs/{gatewayId}/dhwCircuits/{circuitId}/charge endpoint that provides details on charging extra hot water for a specific appliance and its domestic hot water circuit.
• Added the new PATCH /hvacs/{gatewayId}/dhwCircuits/{circuitId}/charge endpoint that allows to enable or disable the hot water charging process for a specific appliance and its domestic hot water circuit.
• Added the new GET /hvacs/{gatewayId}/dhwCircuits/{circuitId}/operationMode endpoint that provides the current operation mode for a specific appliance and its domestic hot water circuit.
• Added the new PUT /hvacs/{gatewayId}/dhwCircuits/{circuitId}/operationMode endpoint that allows to change the operation mode for a specific appliance and its domestic hot water circuit.
• Extended the domain model with the DhwCircuitsCharge and DhwOperationMode objects.
• Added new GET /hvacs/{gatewayId}/heatingCircuits/{circuitId} endpoint that provides details about a specific heating circuit for a specific appliance.
• Added new PATCH /hvacs/{gatewayId}/heatingCircuits/{circuitId} endpoint that allows to update a specific heating circuit for a specific appliance.
• Extended the domain model with the HeatingCircuit object.
• Removed customerId from the GET /contract response.
• Added userID to the GET /contract response.
• Extended the Security section with information on the new x-user-id header required for remote control endpoints, and the approval of the latest consent version by the appliance owner as a precondition.
• Added additional information about the expiration of the API Key.
• Improved documentation about connectivity status retrieval via GET /status.
• Added documentation about known use cases limitations. This new section is now available here.
• Simplified and restructure the documentation inside the Developer Portal.
• Added new data points hvac.emon.compressor.powerCurrent and hvac.emon.eheater.powerCurrent to the webhook notifications.

2024-06-14

• Added additional information about the expiration of the API Key.

2024-06-03

• Fixed a bug where appliance status events with unsupported languages were not forwarded to partners. Now all languages supported by HomeCom Pro are supported by the Partner API.

2024-05-15

• ConnectivityStatusEvent event model has been extended to include the timestamp to represent the instant at which the connectivity status was updated. The domain model was adjusted accordingly.

2024-04-29

• Improved data resolution for hvac.emon data points representing kWh values by increasing decimal places from one to two.

2024-04-02

• Added new data points hvac.emon.compressor.operationStatus and hvac.emon.eheater.operationStatus to the webhook notifications.

2024-04-01

• Added new data points to the webhook notifications.
• ApplianceStatusEvent event model has been extended to include the description of the error in the languages that were specified during the onboarding process. The domain model was updated accordingly.

2024-03-18

• Fixed data inconsistency between Partner API and HomeCom Pro: The ApplianceStatusEvent now correctly reports the status of the appliance as it is shown in HomeCom Pro.
• Removed the duplicated eventType field in the DataPointEvent payload.
• Fixed the unit of measure from KWH to kWh in the DataPointEvent payload.

2024-03-05

• Added new terms to the glossary section.

2024-02-20

• Added documentation about HomeCom Pro direct links that any partner can use.
• Added documentation about which data point types are supported.
• Updated the documentation about webhooks to provide details about the supported event notification types, including the new data point notifications.
• Updated the domain model to include the data point event.

2024-01-04

• Webhook event names renamed respectively from ErrorEvent to ApplianceStatusEvent and ConnectivityEvent to ConnectivityStatusEvent
• Updated the ApplianceStatusEvent
  • timestamp field has been renamed to createdAt.
  • category field has been removed, since it is not providing useful information.
  • severity field has been removed. Use applianceStatus instead.
• Updated the documentation about webhooks, giving additional detail to the rules behind the Bosch filtering and classification process of appliance status events.

2023-12-01

• GET /components endpoint now provides all the components (besides the Gateway component) detected in the HVAC.
• GET /contract response field street was renamed to addressLines.
• Updated the API reference page with the preconditions to invoke each endpoint.

2023-11-09

• Added GET /contract endpoint to retrieve HVAC contract details.

2023-10-20

• Added GET /status endpoint to retrieve HVAC status.
• Added GET /components endpoint to enable system detection.
• Added connectivity status (ONLINE/OFFLINE) as event type.
• Moved event payload description from webhooks section to API Reference.

2023-09-01

• Added GET /hvacs endpoint to retrieve all HVACs a partner has access to.
• Added GET /health endpoint to fetch the operating status of the Partner API.
• Added webhooks to deliver events asynchronously. See docs here.
• Added error event as type.
• Added unique requestId to track specific requests in support cases. See docs here.
• Added initial documentation to Developer Portal.