API reference

Endpoint overview

The table below lists the most commonly used endpoints.

Method	Endpoint	Description
GET	`/gateways`	Hub metadata
GET	`/domain_objects`	All available objects (locations, appliances, modules)
GET	`/locations`	All locations
GET	`/modules`	All physical hardware modules. A modules
GET	`/appliances`	All virtual appliances, that are/aren't attached to a module (physical hardware module)

Additional endpoints for logs and control operations are described in the following chapters.

Gateway Metadata

GET /core/gateways

Returns system information about the local Plugwise Hub, including firmware version, IP address, MAC address, feature flags, hardware model, and configuration environment. This endpoint is typically used to identify the device and its capabilities.

Path Parameters

None

Filter Parameters

None

Response

The most relevant attributes are listed below. Note that the response schema is shared across multiple Plugwise products, including Anna, Adam, and Smile P1. As a result, some attributes may appear in the response but are unused or irrelevant for certain models. These can safely be ignored.

Attribute	Type	Description
`enabled`	boolean	Whether the gateway is active
`firmware_version`	string	Current firmware version
`mac_address`	string	LAN MAC address
`wifi_mac_address`	string	Wi-Fi MAC address
`short_id`	string	8-character ID of the Hub used for authentication
`vendor_name`	string	Manufacturer name
`vendor_model`	string	Product model, e.g. `smile_thermo`
`lan_ip`	string	Latest known LAN IP address (if available)
`wifi_ip`	string	Latest known WiFi IP address (if available)
`hostname`	string	Hostname of the Hub
`features`	object	List of enabled feature modules (e.g. `cooling`, `remote_control`)
`gateway_environment`	object	Metadata about the household, tariffs, and geographic location
`project`	object	Optional project info (e.g. for provisioning or inventory tracking)

Example request

GET /core/gateways

Example response

<gateways>
  <gateway id="6f4b9c58c66b4c8784014b92584aa1f8">
	<created_date>2023-06-27T10:08:06.128+02:00</created_date>
	<modified_date>2025-08-08T05:46:15.755+02:00</modified_date>
	<deleted_date/>
	<name/>
	<description/>
	<enabled>true</enabled>
	<firmware_locked>false</firmware_locked>
	<prevent_default_update>false</prevent_default_update>
	<last_reset_date>2023-06-27T10:08:06.128+02:00</last_reset_date>
	<last_boot_date>2025-08-05T02:23:05.354+02:00</last_boot_date>
	<vendor_name>Plugwise</vendor_name>
	<vendor_model>smile</vendor_model>
	<hardware_version>AME Smile 2.0 board</hardware_version>
	<firmware_version>4.4.4</firmware_version>
	<mac_address>C49300062592</mac_address>
	<wifi_mac_address>C49300062591</wifi_mac_address>
	<short_id>fxzrqxpp</short_id>
	<send_data>true</send_data>
	<anonymous>false</anonymous>
	<lan_ip/>
	<wifi_ip>192.168.1.188</wifi_ip>
	<hostname>smile062592</hostname>
	<time>2025-08-08T10:27:08+02:00</time>
	<timezone>Europe/Amsterdam</timezone>
	<ssh_relay>disabled</ssh_relay>
	<project id="123306def5eb4172ae74435aea21e753">
		<is_default>false</is_default>
		<name>Z -- Stock</name>
		<visible_in_production>true</visible_in_production>
		<description>Stock which was previously called fulfillment</description>
		<modified_date>2023-06-27T10:08:06.266+02:00</modified_date>
		<created_date>2014-11-19T17:45:10+01:00</created_date>
		<deleted_date/>
	</project>
    <features>
		<remote_control id="4bc08ed44b7c42a5b78d50b791e8a36b">
			<validity_period/>
			<expiration_date>2038-01-19T04:14:07+01:00</expiration_date>
			<valid_from/>
			<valid_to/>
			<activation_date/>
			<grace_period/>
			<modified_date>2025-05-20T09:40:06.310+02:00</modified_date>
			<created_date>2025-05-19T15:17:30+02:00</created_date>
			<deleted_date/>
		</remote_control>
    </features>
	<gateway_environment id="3185c8520118480e8fe3c563dc105cc8">
		<postal_code/>
<electricity_production_tariff_structure>double</electricity_production_tariff_structure>
		<latitude/>
		<longitude/>
		<savings_result_value/>
		<central_heating_brand/>
		<central_heating_model/>
		<central_heating_year_of_manufacture/>
		<central_heating_installation_date/>
		<thermostat_brand/>
		<thermostat_model/>
		<modified_date>2022-11-19T22:42:44.001+01:00</modified_date>
		<currency>EUR</currency>
		<housing_type>apartment</housing_type>
		<housing_construction_period>unknown</housing_construction_period>
		<household_adults>0</household_adults>
		<household_children>0</household_children>		<electricity_consumption_peak_tariff>0.237</electricity_consumption_peak_tariff><electricity_consumption_off_peak_tariff>0.222</electricity_consumption_off_peak_tariff>
		<electricity_production_single_tariff/>
	<electricity_production_peak_tariff>0.237</electricity_production_peak_tariff>
<electricity_production_off_peak_tariff>0.222</electricity_production_off_peak_tariff>
		<tariff_region>NL</tariff_region>
		<electricity_consumption_single_tariff/>
		<country/>
		<gas_consumption_tariff>1.85</gas_consumption_tariff>	<electricity_consumption_tariff_structure>double</electricity_consumption_tariff_structure>
		<city/>
		<savings_result_unit/>
		<created_date>2025-08-07T04:48:55+02:00</created_date>
		<deleted_date/>
		<modified_date>2022-11-19T22:42:44.001+01:00</modified_date>
	</gateway_environment>
  </gateway>
</gateways>

Locations

GET /core/locations{;id={location_id}}

This endpoint retrieves all locations configured in the system. Locations represent logical groupings such as rooms, zones, or the building itself. They are used to organise appliances and aggregate measurements.

A location may contain references to appliances, measurement logs, and actuator functionalities such as thermostat control.

Scope parameters

Parameter	Type	Description
`location_id`	string	Optional. Limits the result to a single location. If omitted, all locations are returned.

Filter parameters

Parameter	Type	Description
`type`	string	Filter by location type (e.g. `livingroom`, `building`)
`preset`	string	Filter by active preset (e.g. `home`, `away`, `asleep`)
`@from`	string	Start of time range for logs (ISO 8601)
`@to`	string	End of time range for logs (ISO 8601)
`@interval`	string	Aggregation interval for logs (e.g. `PT1H`, `P1D`)

Response

Returns a <locations> element containing one or more <location> elements.

Response attributes

Field	Type	Description
location `id`	string	Unique identifier of the location
`name`	string	Display name
`description`	string	Description
`type`	string	Location type
`created_date`	datetime	Timestamp when the location was created
`modified_date`	datetime	Timestamp of the last update
`preset`	string	Current preset
`appliances`	list	References to linked appliances
`logs`	object	Measurement logs
`actuator_functionalities`	object	Control functionalities (e.g. thermostat control)

Example request

GET /core/locations

Example response

<locations>
	<location id="4e2d2dc36bb94fe494b1b71794d46c99">
		<name>Living room</name>
		<description>The room containing the (central) home thermostat.</description>
		<type>livingroom</type>
		<created_date>2024-01-12T10:27:02.596+01:00</created_date>
		<modified_date>2025-08-08T14:40:17.645+02:00</modified_date>
		<deleted_date/>
		<preset>asleep</preset>
		<clients/>
		<appliances>
			<appliance id="b9a28f3d3c4b4972bbb2c325e64c1bc6"/>
		</appliances>
		<logs>
			<!-- more data -->
		</logs>
		<actuator_functionalities>
			<!-- more data -->
		</actuator_functionalities>
	</location>
	<location id="80ea9c3b292e4d65bf192011929df27b">
		<name>Home</name>
		<description>A building with a smart meter.</description>
		<type>building</type>
		<created_date>2023-06-27T10:08:07.308+02:00</created_date>
		<modified_date>2025-08-08T14:45:33.894+02:00</modified_date>
		<deleted_date/>
		<preset>home</preset>
		<clients/>
		<appliances/>
		<logs>
			<!-- more data -->
		</logs>
		<actuator_functionalities/>
	</location>
</locations>

Modules

GET /core/modules{;id={module_id}}

This endpoint retrieves all detected modules (hardware components) available in the system. Modules represent physical devices such as thermostats, gateways, meters, sensors, or actuators.

Each module contains vendor metadata, firmware and hardware information, and exposes available services and supported communication protocols.

Results can optionally be filtered to a specific module or limited based on vendor and hardware characteristics.

Scope parameters

Parameter	Type	Description
`module_id`	string	Optional. Limits the result to a single module. If omitted, all modules are returned.

Filter Parameters

Parameter	Type	Description
`vendor_name`	string	Filter by vendor or manufacturer name
`vendor_model`	string	Filter by device model
`hardware_version`	string	Filter by exact hardware version

Parameters are combined using semicolon syntax:

/core/modules;vendor_name=Plugwise;vendor_model=ThermoTouch

Response

Returns a <modules> element containing one or more <module> elements.

Field	Type	Description
module `id`	string	Unique identifier of the module
`vendor_name`	string	Manufacturer name
`vendor_model`	string	Model identifier
`hardware_version`	string	Hardware version, if available
`firmware_version`	string	Firmware version, if available
`created_date`	datetime	Timestamp when the module was first detected
`modified_date`	datetime	Timestamp of the last update
`deleted_date`	datetime	Timestamp when the module was marked as deleted, if applicable
`services`	object	Available services exposed by the module
`protocols`	object	Supported communication protocols

Example request

GET /core/modules

Example response

<modules>
	<module id="8740d6cfa87a459cb4a5c4e048e3f679">
	<vendor_name>SHENZHEN KAIFA TECHNOLOGY （CHENGDU） CO., LTD.</vendor_name>
	<vendor_model>KFM5KAIFA-METER</vendor_model>
	<hardware_version/>
	<firmware_version/>
	<created_date>2018-03-02T19:08:49.705+01:00</created_date>
	<modified_date>2025-08-08T15:35:19.567+02:00</modified_date>
	<deleted_date/>
	<services>
		<electricity_cumulative_meter id="8e89f0811b8b488e8fda9d15894abc1d" log_type="electricity">
			<functionalities>
			<cumulative_log id="2a43670086cd42c1b93d6164f77eeb76"/>
			<cumulative_log id="ce87248211f640bb9199971e4e49c4f4"/>
			</functionalities>
		</electricity_cumulative_meter>
		<!-- more data -->
		</services>
	<protocols>
		<dsmr_main id="985ac1e6488b42459a7a02ff4c850c1f">
		<serial>E0002000000122113</serial>
		<version>42</version>
		<dsmr_mbuses/>
		</dsmr_main>
	</protocols>
	</module>
</modules>

Appliances

GET /core/appliances{;id={appliance_id}}

This endpoint retrieves all appliances configured in the system. Appliances represent logical devices that expose measurements (logs) and control capabilities (actuator functionalities).

An appliance is typically backed by one or more modules and provides a higher-level representation of a controllable or measurable entity, such as a thermostat, smart plug, or radiator valve.

Scope parameters

Parameter	Type	Description
`appliance_id`	string	Optional. Limits the result to a single appliance. If omitted, all appliances are returned.

Response

Returns an <appliances> element containing one or more <appliance> elements.

Response attributes

Field	Type	Description
appliance `id`	string	Unique identifier of the appliance
`name`	string	Human-readable name
`description`	string	Description of the appliance
`type`	string	Appliance type
`created_date`	datetime	Timestamp when the appliance was created
`modified_date`	datetime	Timestamp of the last update
`deleted_date`	datetime	Timestamp when the appliance was deleted, if applicable
`groups`	object	Group memberships, if any
`logs`	object	Measurement data exposed by the appliance
`actuator_functionalities`	object	Available control functionalities

Logs

The <logs> element contains one or more <point_log>, <interval_log>, or <cumulative_log> elements representing measurements such as temperature, energy usage, or device state.

Actuator functionalities

The <actuator_functionalities> element exposes the controllable features of the appliance, such as thermostat setpoints or relay switching.

Example request

GET /core/appliances

Example response

<appliances>  
	<appliance id="c28a68a92d3b4f9f839c76d1b57fd3a5">  
		<name>Tom</name>  
		<type>thermostatic_radiator_valve</type>  
		<logs>  
			<point_log id="71c6fa514d9343e7af611676717fa2ed">  
				<type>temperature</type>  
				<unit>C</unit>  
				<updated_date>2026-02-17T10:47:43.502+01:00</updated_date>  
				<period start_date="2026-02-17T10:47:43.502+01:00" end_date="2026-02-17T10:47:43.502+01:00">  
					<measurement log_date="2026-02-17T10:47:43.502+01:00">21.12</measurement>  
				</period>  
			</point_log>  
		</logs>  
		<actuator_functionalities>  
			<thermostat_functionality id="c23d82ba47264ffbb6f8a8ef1baee161">  
				<setpoint>17</setpoint>  
			</thermostat_functionality>  
		</actuator_functionalities>  
	</appliance>  
</appliances>

Endpoint overview​

Gateway Metadata​

Path Parameters​

Filter Parameters​

Response​

Example request​

Example response​

Locations​

Scope parameters​

Filter parameters​

Response​

Response attributes​

Example request​

Example response​

Modules​

Scope parameters​

Filter Parameters​

Response​

Example request​

Example response​

Appliances​

Scope parameters​

Response​

Response attributes​

Logs​

Actuator functionalities​

Example request​

Example response​

Endpoint overview

Gateway Metadata

Path Parameters

Filter Parameters

Response

Example request

Example response

Locations

Scope parameters

Filter parameters

Response

Response attributes

Example request

Example response

Modules

Scope parameters

Filter Parameters

Response

Example request

Example response

Appliances

Scope parameters

Response

Response attributes

Logs

Actuator functionalities

Example request

Example response