Getting started

This document describes the local HTTP API exposed by Plugwise hubs. It is intended for developers and technical integrators who want to retrieve device data, inspect the system model, and control supported functions directly on the local network.

The API uses XML over HTTP and is available on the hub itself. It provides access to core resources such as gateways, locations, modules, appliances, logs, and actuator functionalities. Depending on the connected devices and the product type, the API can be used to read measurements such as electricity usage, temperature, and device state, and to control supported functions such as relay switching.

The same API structure is used across multiple Plugwise hub-based products. As a result, some resources or attributes may be present in the schema but not relevant for every installation or product configuration.

Accessing the hub API Locally

Plugwise Hubs expose a local HTTP API that can be accessed from devices on the same local network (LAN). You can connect to the Hub using one of the following methods:

Method	Endpoint	Notes
Local IP address	http://{ip_address}	Recommended for stability (consider setting a static DHCP lease)
Hostname (mDNS)	http://smile{mac_suffix}.local	{mac_suffix} = last 6 characters of the LAN MAC address. Requires mDNS/Bonjour support. Can be found on the label on the back of the hub.
Cloud announce endpoint	https://auth.plugwise.net/announce/{hub_id}	Returns the last known local IP address. Useful for discovery.

mDNS generally works reliably on local networks without subnets, especially on Apple devices, but may require additional setup or fail across isolated networks or non-mDNS-capable clients.

---

Announce Endpoint

Plugwise provides a cloud-based announce endpoint that returns the Hub’s last known IP address on your local network in XML format. Use this endpoint to find your Hub's local IP address, then connect directly to the API using that address.

GET https://auth.plugwise.net/announce/announce/{hub_id}

This is the only step that requires an endpoint on auth.plugwise.net. All other API requests are done via the local ip address of the hub.

Path parameters

Parameter	Type	Description
hub_id	string	8-character identifier of the hub

Response attributes

Field	Type	Description
product	string	Type of product: • smile = Smile P1 • smile_thermo = Anna, Anna P1 • smile_open_therm = Adam SA, Adam HA
version	string	Current firmware version of the Hub
lan_ip	string	Last known local IP address Ethernet (if available)
wifi_ip	string	Last known local IP address Wi-Fi ( if available)
timestamp	datetime	Timestamp of when the IP info was last updated (local time)

Example request

GET https://auth.plugwise.net/announce/fxzrqxpp

Example response

<beacon>
	<product>smile</product>
	<version>4.4.4</version>
	<lan_ip/>
	<wifi_ip>192.168.1.188</wifi_ip>
	<timestamp>2025-08-08T09:33:04.000+02:00</timestamp>
	<rest_root>/</rest_root>
	<server_timestamp>2025-08-08T07:33:04+00:00</server_timestamp>
</beacon>

---

Authentication

All requests to the local API of a Plugwise Hub require HTTP Basic Authentication.

Field	Value
Username	smile
Password	8-character hub ID

The Hub ID can be found on the label on the bottom of the hub.

Request Format

Use Basic Auth headers in your HTTP request. Example in curl:

curl -u "smile:fxzrqxpp" http://192.168.1.136/core/gateways

---

Base URL and API conventions

Once you've located the Hub, all endpoints are accessible under /core/ path:

http://{hub-address}/core/

Example request

GET http://192.168.1.188/core/gateways

Request format

• Protocol: HTTP
• Authentication: Basic Auth
• Payload format: XML
• Encoding: UTF-8

Parameter syntax

This API uses semicolon-separated parameters instead of traditional query strings.

/core/appliances;id={uuid}  
/core/locations;type=livingroom;preset=home

Multiple parameters can be combined:

/core/modules;vendor_name=Plugwise;vendor_model=160-01

Scope vs filter parameters

• Scope parameters define which resource(s) are targeted. Example:

/core/appliances;id={appliance_id}

• Filter parameters refine the returned data.
  Example:

/core/locations;type=livingroom

Time parameters

Time-based filters use ISO 8601 format (UTC unless stated otherwise):

Parameter	Description
@from	Start of time range
@to	End of time range
@interval	Aggregation interval (e.g. PT1H, P1D)

Default behaviour (logs)

If no @from and @to parameters are provided, logs return data based on the most recent available measurements per log. This is evaluated independently per log, meaning results may contain data from different dates.