Documentation

Venstar Thermostat Local API enables simple integration with other compatible systems. Use our modern REST API to discover and control Venstar thermostats via the local network.

Simple Service Discovery Protocol

The Simple Service Discovery Protocol (SSDP) is a network protocol based on the Internet Protocol Suite for advertisement and discovery of network services and presence information. It accomplishes this without assistance of server-based configuration mechanisms, such as the Dynamic Host Configuration Protocol (DHCP) or the Domain Name System (DNS), and without special static configuration of a network host. SSDP is the basis of the discovery protocol of Universal Plug and Play and is intended for use in residential or small office environments.

SSDP is a text-based protocol based on HTTPU. It uses the User Datagram Protocol (UDP) as the underlying transport protocol. Services are announced by the hosting system with multicast addressing to a specifically designated IP multicast address 239.255.255.250 at UDP port number 1900.

In order to discover Venstar thermostats on your local network, your application can send the following M-SEARCH message using the HTTP protocol to the SSDP multicast address and port.
M-SEARCH * HTTP/1.1
Host: 239.255.255.250:1900
Man: ssdp:discover
ST: venstar:thermostat:ecp
Venstar thermostats will respond with the following message when they receive a valid M-SEARCH message.
HTTP/1.1 200 OK
Cache-Control: max-age=300
ST: venstar:thermostat:ecp
Location: http://192.168.1.100:8080/
USN: colortouch:ecp:00:23:a7:3a:b2:72:name:Living%20Room:type:residential

Location header is the URL for the Venstar Thermostat Local API service. The thermostat name is contained in the USN header. If you have multiple Venstar thermostats on your network, your application can receive multiple packets with different locations and names.

At a regular interval Venstar thermostats broadcast their services by sending a NOTIFY message similar to the response message above to the multicast address and port. NOTIFY messages replace the ST header with NT. If your application has not received a new NOTIFY message before the Cache-Control expires, Venstar thermostat is no longer available on the network.

API Information

This request returns the current API version and the type of Venstar thermostat. Thermostat type is either
residential or commercial.

GET /

Example:
http://192.168.1.100/
Response:
{
api_ver: 4,
type: 'residential'
}

Query general information

This request returns a list of settings needed to render the home screen of a thermostat.

GET /query/info

Example:
http://192.168.1.100/query/info
Response:
{
name: 'Office',
mode: 0,
state: 0,
fan: 0,
fanstate: 0,
tempunits: 0,
schedule: 0,
schedulepart: 0,
away: 0,
holiday: 0,
override: 0,
overridetime: 0,
forceunocc: 0,
spacetemp: 79,
heattemp: 78,
cooltemp: 75,
cooltempmin: 35,
cooltempmax: 99,
heattempmin: 35,
heattempmax: 99,
setpointdelta: 2,
hum: 50,
availablemodes: 0
}

Query sensors

This request returns a list of all the thermostat's sensors.

GET /query/sensors

Example:
http://192.168.1.100/query/sensors
Response:
{
sensors: [
{
name: 'Thermostat',
temp: 77
},
{
name: 'Outdoor',
temp: 0
}
]
}

Query runtimes

This request returns the runtime data of a thermostat.

GET /query/runtimes

Example:
http://192.168.1.100/query/runtimes
Response:
{
runtimes: [
{
ts: 2147483647,
heat1: 0,
heat2: 0,
cool1: 0,
cool2: 0,
aux1: 0,
aux2: 0,
fc: 0
},
{
ts: 2147483647,
heat1: 0,
heat2: 0,
cool1: 0,
cool2: 0,
aux1: 0,
aux2: 0,
ov: 0
}
]
}

Query alerts

This request returns a list of alert states for a thermostat.

GET /query/alerts

Example:
http://192.168.1.100/query/alerts
Response:
{
alerts: [
{
name: 'Air Filter',
active: false
},
{
name: 'UV Lamp',
active: false
}
{
name: 'Service',
active: false
}
]
}

Control

This request enables remote control of a Venstar thermostat over the network. This command is submitted via an HTTP POST and is URL encoded instead of JSON.

POST /control

Example Request
POST /control HTTP/1.1
Content-Type: application/x-www-form-urlencoded
mode=0&fan=0&heattemp=70&cooltemp=75
Control request requirements
All control calls with mode must include heattemp and cooltemp parameters. When setting mode to Auto, cooltemp must be greater than heattemp and the setpointdelta from '/query/info' needs to be respected. A security PIN is required when Screenlock settings are enabled.
Success Response
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 17
{'success':true}
Error Response
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 14
{'error':true}

Settings

This request enables changing settings of a Venstar thermostat over the network. This command is submitted via an HTTP POST and is URL encoded instead of JSON.

Settings request requirements
A security PIN is required when Screenlock settings are enabled.

POST /settings

Example Request
POST /settings HTTP/1.1
Content-Type: application/x-www-form-urlencoded
tempunits=0&away=0&schedule=0&hum_setpoint=0&dehum_setpoint=0
Success Response
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 17
{'success':true}
Error Response
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 17
{'error':true}

Error Handling

Unsuccessful requests return a JSON object with error property and a reason describing the error. If the endpoint is unavailable, appropriate HTTP response is returned.

POST /settings

Error Response
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 39
{''error':true, 'reason':'error reason'}