ecobee Home Developer API

https://www.ecobee.com/home/developer/api/documentation/v1/
Admin
ecobee Home Developer API is a REST API that enables developers to authorize, read, and control...
Tokens:100,664
Snippets:810
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### GET Group Request Example

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-group.shtml

This example shows how to construct a GET request to retrieve group information. Ensure the 'selectionType' is set to 'registered'.

```http
GET https://api.ecobee.com/1/group?format=json&body={"selection":{"selectionType":"registered"}}
```

--------------------------------

### Example Absolute Redirect URI

Source: https://www.ecobee.com/home/developer/api/documentation/v1/auth/developer-migration-summary.shtml

This is an example of an absolute redirect URI that must be used with the updated authentication system. It must start with https:// and cannot include port numbers.

```text
https://myapplication.com/oauth/callback
```

--------------------------------

### Thermostat Summary Request with Equipment Status

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-thermostat-summary.shtml

This example shows how to construct a GET request to the thermostatSummary endpoint, including the 'includeEquipmentStatus' parameter to retrieve detailed equipment status for each thermostat.

```http
GET https://api.ecobee.com/1/thermostatSummary?json={"selection":{"selectionType":"registered","selectionMatch":"","includeEquipmentStatus":true}}
HEADERS:
	Content-Type: application/json;charset=UTF-8
	Authorization: Bearer Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg
```

--------------------------------

### Request Runtime Report Job Status (GET)

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-list-runtime-report-job.shtml

This example shows how to make a GET request to retrieve the status of a specific runtime report job or all current job statuses for the account. Ensure to include the 'jobId' in the query parameters if a specific job status is needed. The 'Content-Type' and 'Authorization' headers are required.

```HTTP
GET https://api.ecobee.com/1/runtimeReportJob/status?format=json&body={"jobId":"123"}
HEADERS:
	Content-Type: application/json;charset=UTF-8
	Authorization: Bearer ACCESS_TOKEN
```

--------------------------------

### Example Page Request for GET Thermostats

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-intro.shtml

This JSON payload demonstrates how to request a specific page of thermostat data. Include the 'page' object with the desired 'page' number in your GET Thermostats request body.

```json
{
	"selection": {
		"selectionType": "managementSet",
		"selectionMatch": "/"
	},
	"page": {
		"page": 2
	}
}
```

--------------------------------

### Example Response for Get List Hierarchy Users

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/hierarchy/get-list-hierarchy-users.shtml

This JSON object represents a typical response from the Get List Hierarchy Users API, detailing users and their privileges.

```json
{
    "users": [
        {
            "userName": "api@ecobee.com",
            "firstName": "",
            "lastName": "",
            "phone": "",
            "lastLogin": "2008-01-02 00:00:00",
            "active": true,
            "emailAlerts": true
        },
        {
            "userName": "api2@ecobee.com",
            "firstName": "",
            "lastName": "",
            "phone": "",
            "lastLogin": "2008-01-02 00:00:00",
            "active": true,
            "emailAlerts": true
        }
    ],
    "privileges": [
        {
            "setPath": "/",
            "setName": "My Sets",
            "userName": "api@ecobee.com",
            "allowAll": true,
            "allowNone": false,
            "allowView": false,
            "allowProgram": false,
            "allowVacation": false,
            "allowSettings": false,
            "allowDetails": false,
            "allowReport": false,
            "allowSecurity": false,
            "allowHierarchy": false,
            "allowAlerts": false,
            "allowManageAccount": false
        },
        {
            "setPath": "/",
            "setName": "My Sets",
            "userName": "api2@ecobee.com",
            "allowAll": false,
            "allowNone": true,
            "allowView": false,
            "allowProgram": false,
            "allowVacation": false,
            "allowSettings": false,
            "allowDetails": false,
            "allowReport": false,
            "allowSecurity": false,
            "allowHierarchy": false,
            "allowAlerts": false,
            "allowManageAccount": false
        },
        {
            "setPath": "/MainNode/SubNode1",
            "setName": "SubNode1",
            "userName": "api2@ecobee.com",
            "allowAll": false,
            "allowNone": false,
            "allowView": true,
            "allowProgram": false,
            "allowVacation": false,
            "allowSettings": false,
            "allowDetails": false,
            "allowReport": false,
            "allowSecurity": false,
            "allowHierarchy": false,
            "allowAlerts": false,
            "allowManageAccount": false
        },
        {
            "setPath": "/OtherNode",
            "setName": "OtherNode",
            "userName": "api2@ecobee.com",
            "allowAll": false,
            "allowNone": false,
            "allowView": false,
            "allowProgram": false,
            "allowVacation": false,
            "allowSettings": false,
            "allowDetails": false,
            "allowReport": false,
            "allowSecurity": false,
            "allowHierarchy": true,
            "allowAlerts": false,
            "allowManageAccount": false
        }
    ],
    "status": {
        "code": 0,
        "message": ""
    }
}
```

--------------------------------

### Example Management Set Paths

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/hierarchy/getting-started-management-set-hierarchy.shtml

These are examples of valid management set path strings, illustrating root, single-level, and nested hierarchies. The root set is represented by '/'.

```text
/
/Location 1
/Location 1/Group 1
/Location 1/Group 2
/Location 2
/Location 2/Group 1
```

--------------------------------

### Request Body Example

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/hierarchy/post-move-thermostat.shtml

This is an example of the JSON request body for moving thermostats. Ensure the 'operation' is set to 'move', and provide valid 'setPath', 'toPath', and optionally 'thermostats'.

```json
{
  "operation": "move",
  "setPath": "/MainNode",
  "toPath": "/OtherNode",
  "thermostats": "123456789012,123456789013"
}
```

--------------------------------

### Example Legacy Redirect URI

Source: https://www.ecobee.com/home/developer/api/documentation/v1/auth/developer-migration-summary.shtml

This is an example of a legacy redirect URI format that was previously accepted. The new system requires absolute URIs.

```text
myapplication.com
```

--------------------------------

### Get Thermostats (cURL)

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-thermostats.shtml

Use this cURL command to retrieve thermostat information. Ensure you replace ACCESS_TOKEN with your valid authorization token. This example includes runtime, events, and settings.

```shell
curl -X GET 'https://api.ecobee.com/1/thermostat?json=\{"selection":\{"selectionType":"thermostats","selectionMatch":"","includeRuntime":true,"includeEvents":"true","includeSettings":"true"\}\}' -H 'Authorization: Bearer ACCESS_TOKEN' -H 'Content-Type: application/json;charset=UTF-8' -H 'cache-control: no-cache'
```

--------------------------------

### GET Thermostats Request

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-response.shtml

Example of a GET request to retrieve all registered thermostats and their alerts. The request body is URL-encoded and appended to the URL.

```APIDOC
## GET /1/thermostat

### Description
Retrieves all thermostats registered to the user and any alerts they may have.

### Method
GET

### Endpoint
https://api.ecobee.com/1/thermostat?format=json

### Parameters
#### Query Parameters
- **body** (string) - Required - The URL-encoded JSON body of the request, specifying selection criteria and included data.

### Request Example
```
GET https://api.ecobee.com/1/thermostat?format=json&body=%7B%22selection%22%3A%7B%22selectionType%22%3A%22registered%22%2C%22selectionMatch%22%3A%22%22%2C%22includeAlerts%22%3Atrue%7D%7D
```

### Request Body Example (Decoded)
```json
{
  "selection": {
    "selectionType": "registered",
    "selectionMatch": "",
    "includeAlerts": true
  }
}
```

### Headers
- **Content-Type**: application/json;charset=UTF-8
- **Authorization**: Bearer [Your Access Token]
```

--------------------------------

### Example Management Set API Request

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/hierarchy/getting-started-management-set-hierarchy.shtml

This is an example of an unencoded HTTP request to the `/thermostatSummary` endpoint using a management set path. Ensure the `selectionMatch` value is properly URL-encoded if necessary.

```http
https://api.ecobee.com/1/thermostatSummary?json={"selection":{"selectionType":"managementSet","selectionMatch":"/Test Stats"}}
```

--------------------------------

### Example Page Request

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-intro.shtml

Demonstrates how to construct a request to retrieve a specific page of results.

```APIDOC
### Example Page Request
```json
{
  "selection": {
    "selectionType": "managementSet",
    "selectionMatch": "/"
  },
  "page": {
    "page": 2
  }
}
```
```

--------------------------------

### Meter Report Request Body Example

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-meter-report.shtml

This is an example of the JSON request body for the meterReport API. Ensure the 'startDate', 'endDate', 'meters', and 'selection' parameters are correctly formatted.

```json
{
  "startDate": "2013-04-04",
  "endDate": "2013-04-04",
  "meters": "energy",
  "selection": {
    "selectionType": "thermostats",
    "selectionMatch": "123456789012"
  }
}
```

--------------------------------

### Example Get Thermostats API Response

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-thermostats.shtml

This JSON structure represents the data returned when requesting thermostat information. It includes details like thermostat identifier, name, model, serial number, and current settings. Note the '...snip...' indicating omitted details.

```json
{
    "page": {
        "page": 1,
        "totalPages": 1,
        "pageSize": 1,
        "total": 1
    },
    "thermostatList": [
        {
            "identifier": "161775386723",
            "name": "",
            "thermostatRev": "110128234025",
            "isRegistered": true,
            "modelNumber": "Smart",
            "serialNumber": "1",
            "productCode": "1",
            "lastModified": "2011-01-28 23:40:25",
            "alerts": [],
            "settings": {
                "hvacMode": "heat",
                "lastServiceDate": "2011-01-28",
                "serviceRemindMe": false,
                "...snip..."
            }
        }
    ],
    "status": {
        "code": 0,
        "message": ""
    }
}
```

--------------------------------

### GET Request for Thermostats with Alerts

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-response.shtml

Use this GET request to retrieve all thermostats registered to a user along with any associated alerts. Ensure the 'Content-Type' and 'Authorization' headers are correctly set.

```http
HEADERS:
	Content-Type: application/json;charset=UTF-8
	Authorization: Bearer Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg

REQUEST:
	GET https://api.ecobee.com/1/thermostat?format=json&body=%7B%22selection%22%3A%7B%22selectionType%22%3A%22registered%22%2C%22selectionMatch%22%3A%22%22%2C%22includeAlerts%22%3Atrue%7D%7D
```

--------------------------------

### Get Thermostats (JavaScript)

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-thermostats.shtml

This JavaScript snippet demonstrates how to make a GET request to retrieve thermostat data using jQuery's AJAX. It includes necessary headers and specifies which thermostat details to include in the response.

```javascript
$.ajax({
    beforeSend: function(request) {
        request.setRequestHeader("Authorization", "Bearer ".concat(ACCESS_TOKEN));
    },
    dataType: "json",
    url: 'https://api.ecobee.com/1/thermostat?json=\{"selection":\{"includeAlerts":"true","selectionType":"registered","selectionMatch":"","includeEvents":"true","includeSettings":"true","includeRuntime":"true"\}\}',
    success: function(data) {
    	var response = JSON.stringify(data, null, 4);
    }
});
```

--------------------------------

### GET List Sets

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-response.shtml

Retrieves a list of all management sets.

```APIDOC
## GET List Sets

### Description
Retrieves a list of all management sets.

### Method
GET

### Endpoint
/management/sets

### Response
#### Success Response (200)
- **sets** (array) - A list of management set objects.
  - Each object contains details about a management set.
    - **id** (string) - The set identifier.
    - **name** (string) - The name of the set.

#### Response Example
```json
{
  "sets": [
    {
      "id": "setA",
      "name": "Set 1"
    },
    {
      "id": "setB",
      "name": "Set 2"
    }
  ]
}
```
```

--------------------------------

### Example Paged Response

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-intro.shtml

Illustrates the structure of a paged response, including page details and thermostat information.

```APIDOC
### Example Paged Response

A paged response will contain the Page object which contains all page information including the number of pages, and total number of results.
```json
{
  "page": {
    "page": 1,
    "totalPages": 3,
    "pageSize": 10,
    "total": 24
  },
  "thermostatList": [
    {
      "identifier": "123456789012",
      "name": "",
      "thermostatRev": "110128234025",
      "isRegistered": true,
      "modelNumber": "Smart",
      "serialNumber": "1",
      "productCode": "1",
      "lastModified": "2011-01-28 23:40:25",
      "alerts": []
    },
    // Repeated 
  ],
  "status": {
    "code": 0,
    "message": ""
  }
}
```
```

--------------------------------

### Example Paged Response for GET Thermostats

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-intro.shtml

This JSON structure represents a paged response from a GET Thermostats request, including pagination details and a list of thermostat objects. Note that the 'thermostatList' may contain repeated entries.

```json
{
  "page": {
    "page": 1,
    "totalPages": 3,
    "pageSize": 10,
    "total": 24
  },
  "thermostatList": [
    {
      "identifier": "123456789012",
      "name": "",
      "thermostatRev": "110128234025",
      "isRegistered": true,
      "modelNumber": "Smart",
      "serialNumber": "1",
      "productCode": "1",
      "lastModified": "2011-01-28 23:40:25",
      "alerts": []
    },
    // Repeated 
  ],
  "status": {
    "code": 0,
    "message": ""
  }
}
```

--------------------------------

### Update Thermostat with Functions

Source: https://www.ecobee.com/home/developer/api/documentation/v1/functions/using-functions.shtml

This example demonstrates how to specify one or more functions in a thermostat update request. It includes resuming the program and sending a message to the thermostat.

```APIDOC
## POST /thermostat

### Description
Updates a thermostat by applying specified functions in order.

### Method
POST

### Endpoint
/thermostat

### Request Body
- **selection** (object) - Required - Specifies the thermostat(s) to update.
  - **selectionType** (string) - Required - The type of selection (e.g., "registered").
  - **selectionMatch** (string) - Required - The identifier for the selection.
- **functions** (array) - Required - A list of functions to execute on the thermostat.
  - **type** (string) - Required - The type of function (e.g., "resumeProgram", "sendMessage").
  - **params** (object) - Optional - Parameters for the function.
    - **text** (string) - Required for sendMessage - The message text to display on the thermostat.

### Request Example
```json
{
  "selection": {
    "selectionType": "registered",
    "selectionMatch": ""
  },
  "functions": [
    {
      "type": "resumeProgram"
    },
    {
      "type": "sendMessage",
      "params": {
        "text": "I resumed the program"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- The response indicates the success or failure of the function execution. Specific details depend on the API implementation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Example Response for Get List Hierarchy Sets

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/hierarchy/get-list-hierarchy-sets.shtml

This JSON object represents the hierarchical structure of an ecobee account. It details sets, their nested children, user privileges assigned to each set, and thermostats associated with them. The status field indicates the success or failure of the API call.

```json
{
    "sets": [
        {
            "setName": "My Sets",
            "setPath": "/",
            "children": [
                {
                    "setName": "MainNode",
                    "setPath": "/MainNode",
                    "children": [
                        {
                            "setName": "SubNode1",
                            "setPath": "/MainNode/SubNode1",
                            "children": [
                                {
                                    "setName": "SubNode2",
                                    "setPath": "/MainNode/SubNode1/SubNode2",
                                    "children": [],
                                    "privileges": [],
                                    "thermostats": []
                                }
                            ],
                            "privileges": [
                                {
                                    "setPath": "/MainNode/SubNode1",
                                    "setName": "SubNode1",
                                    "userName": "api2@ecobee.com",
                                    "allowAll": false,
                                    "allowNone": false,
                                    "allowView": true,
                                    "allowProgram": false,
                                    "allowVacation": false,
                                    "allowSettings": false,
                                    "allowDetails": false,
                                    "allowReport": false,
                                    "allowSecurity": false,
                                    "allowHierarchy": false,
                                    "allowAlerts": false,
                                    "allowManageAccount": false
                                }
                            ],
                            "thermostats": []
                        }
                    ],
                    "privileges": [],
                    "thermostats": [
                        "123456789012",
                        "123456789013"
                    ]
                },
                {
                    "setName": "OtherNode",
                    "setPath": "/OtherNode",
                    "children": [],
                    "privileges": [
                        {
                            "setPath": "/OtherNode",
                            "setName": "OtherNode",
                            "userName": "api2@ecobee.com",
                            "allowAll": false,
                            "allowNone": false,
                            "allowView": false,
                            "allowProgram": false,
                            "allowVacation": false,
                            "allowSettings": false,
                            "allowDetails": false,
                            "allowReport": false,
                            "allowSecurity": false,
                            "allowHierarchy": true,
                            "allowAlerts": false,
                            "allowManageAccount": false
                        }
                    ],
                    "thermostats": [
                        "123456789014"
                    ]
                }
            ],
            "privileges": [
                {
                    "setPath": "/",
                    "setName": "My Sets",
                    "userName": "api@ecobee.com",
                    "allowAll": true,
                    "allowNone": false,
                    "allowView": false,
                    "allowProgram": false,
                    "allowVacation": false,
                    "allowSettings": false,
                    "allowDetails": false,
                    "allowReport": false,
                    "allowSecurity": false,
                    "allowHierarchy": false,
                    "allowAlerts": false,
                    "allowManageAccount": false
                },
                {
                    "setPath": "/",
                    "setName": "My Sets",
                    "userName": "api2@ecobee.com",
                    "allowAll": false,
                    "allowNone": true,
                    "allowView": false,
                    "allowProgram": false,
                    "allowVacation": false,
                    "allowSettings": false,
                    "allowDetails": false,
                    "allowReport": false,
                    "allowSecurity": false,
                    "allowHierarchy": false,
                    "allowAlerts": false,
                    "allowManageAccount": false
                }
            ],
            "thermostats": []
        }
    ],
    "status": {
        "code": 0,
        "message": ""
    }
}
    
```

--------------------------------

### Example CSV Report Content

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/getting-started-runtime-report-job.shtml

This is an example of the content found within a decrypted CSV report file for a runtime report job.

```text
date | time | zoneCalendarEvent | zoneHVACmode | zoneHeatTemp | zoneCoolTemp | zoneAveTemp | dmOffset  
---|---|---|---|---|---|---|---
2017-13-04 | 0:00:00 | heatOff | heatStage10n | 69 | 60 | 64 | 0  
2017-13-04 | 0:05:00 | heatOff | heatStage10n | 69 | 60 | 64 | 0  
2017-13-04 | 0:10:00 | heatOff | heatStage10n | 69 | 60 | 64 | 0  
.. | .. | .. | .. | .. | .. | .. | ..
```

--------------------------------

### Making Requests

Source: https://www.ecobee.com/home/developer/api/documentation/v1/auth/auth-req-resp.shtml

Guides users on how to make requests to the Ecobee Home Developer API, including request and response formats, and status codes.

```APIDOC
## Making Requests

This section details the process of making requests to the Ecobee Home Developer API, covering request structure, response handling, and common status codes.

### Core Concepts

Understanding the fundamental principles of API interaction, including authentication and data formatting.

### Request and Response

Defines the structure of requests sent to the API and the format of responses received, including common data fields and types.

### Response Codes

Lists and explains the various HTTP status codes returned by the API to indicate the success or failure of a request.
```

--------------------------------

### Example API Response for List Hierarchy Users

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/hierarchy/get-list-hierarchy-users.shtml

This is a sample JSON response from the /hierarchy/user endpoint. It includes a list of users and their associated privileges within the management hierarchy.

```json
{
  "users": [
  {
  "userName": "api@ecobee.com",
  "firstName": "",
  "lastName": "",
  "phone": "",
  "lastLogin": "2008-01-02 00:00:00",
  "active": true,
  "emailAlerts": true
  },
  {
  "userName": "api2@ecobee.com",
  "firstName": "",
  "lastName": "",
  "phone": "",
  "lastLogin": "2008-01-02 00:00:00",
  "active": true,
  "emailAlerts": true
  }
  ],
  "privileges": [
  {
  "setPath": "/",
  "setName": "My Sets",
  "userName": "api@ecobee.com",
  "allowAll": true,
  "allowNone": false,
  "allowView": false,
  "allowProgram": false,
  "allowVacation": false,
  "allowSettings": false,
  "allowDetails": false,
  "allowReport": false,
  "allowSecurity": false,
  "allowHierarchy": false,
  "allowAlerts": false,
  "allowManageAccount": false
  },
  {
  "setPath": "/",
  "setName": "My Sets",
  "userName": "api2@ecobee.com",
  "allowAll": false,
  "allowNone": true,
  "allowView": false,
  "allowProgram": false,
  "allowVacation": false,
  "allowSettings": false,
  "allowDetails": false,
  "allowReport": false,
  "allowSecurity": false,
  "allowHierarchy": false,
  "allowAlerts": false,
  "allowManageAccount": false
  },
  {
  "setPath": "/MainNode/SubNode1",
  "setName": "SubNode1",
  "userName": "api2@ecobee.com",
  "allowAll": false,
  "allowNone": false,
  "allowView": true,
  "allowProgram": false,
  "allowVacation": false,
  "allowSettings": false,
  "allowDetails": false,
  "allowReport": false,
  "allowSecurity": false,
  "allowHierarchy": false,
  "allowAlerts": false,
  "allowManageAccount": false
  },
  {
  "setPath": "/OtherNode",
  "setName": "OtherNode",
  "userName": "api2@ecobee.com",
  "allowAll": false,
  "allowNone": false,
  "allowView": false,
  "allowProgram": false,
  "allowVacation": false,
  "allowSettings": false,
  "allowDetails": false,
  "allowReport": false,
  "allowSecurity": false,
  "allowHierarchy": true,
  "allowAlerts": false,
  "allowManageAccount": false
  }
  ],
  "status": {
  "code": 0,
  "message": ""
  }
  }
```

--------------------------------

### Common Request Parameters

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-intro.shtml

These parameters are common across various requests, including 'body' for GET requests and 'format' for GET and POST requests.

```APIDOC
## Common Request Parameters

The following common request parameters:

Parameter | HTTP Method | Example | Description  
---|---|---|---
body | GET | ?body={ "selection" [ "selectionType": ... ] } | The JSON GET request content. The JSON string must be properly URL encoded in the request URL.  
format | GET, POST | ?format=json | Optional. Informs the API that the request body contains JSON encoding. The API will respond with the same encoding. 'json' is the default and only encoding currently supported.
```

--------------------------------

### GET Thermostat Summary (Polling)

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-thermostats.shtml

Retrieves a summary of the thermostat's current status, often used for polling to get the latest information.

```APIDOC
## GET Thermostat Summary (Polling)

### Description
Retrieves a summary of the thermostat's current status, often used for polling to get the latest information.

### Method
GET

### Endpoint
/thermostat

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Specifies which fields to return in the response. For example, `thermostat(nickname,settings)`.

### Response
#### Success Response (200)
- **thermostat** (object) - An object containing thermostat details.
  - **nickname** (string) - The user-defined nickname for the thermostat.
  - **settings** (object) - An object containing various thermostat settings.

#### Response Example
```json
{
  "thermostat": {
    "nickname": "Living Room",
    "settings": {
      "hvacMode": "auto",
      "fanMode": "auto"
    }
  }
}
```
```

--------------------------------

### POST Add Set

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-response.shtml

Creates a new management set.

```APIDOC
## POST Add Set

### Description
Creates a new management set.

### Method
POST

### Endpoint
/management/sets

### Parameters
#### Request Body
- **name** (string) - Required - The name for the new management set.

### Request Example
```json
{
  "name": "New Set"
}
```

### Response
#### Success Response (200)
- **id** (string) - The identifier of the newly created set.
- **name** (string) - The name of the newly created set.

#### Response Example
```json
{
  "id": "setXYZ",
  "name": "New Set"
}
```
```

--------------------------------

### Decoded GET Request Body

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-response.shtml

This is the decoded JSON body for the GET request to retrieve thermostat data with alerts. It specifies the selection criteria for the thermostats.

```json
{"selection":{"selectionType":"registered","selectionMatch":"","includeAlerts":true}}
```

--------------------------------

### Request Thermostat Summary with Equipment Status (JavaScript)

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-thermostat-summary.shtml

This JavaScript snippet demonstrates how to make a request for thermostat summary data, including equipment status, using jQuery's AJAX method. Remember to replace ACCESS_TOKEN with your actual token.

```JavaScript
$.ajax({
    beforeSend: function(request) {
        request.setRequestHeader("Authorization", "Bearer ".concat(ACCESS_TOKEN));
    },
    dataType: "json",
    url: 'http://localhost:8080/home/api/1/thermostatSummary?json=\{"selection":\{"selectionType":"registered","selectionMatch":"","includeEquipmentStatus":true\}\}',
    success: function(data) {
    	var response = JSON.stringify(data, null, 4);
    }
});
```

--------------------------------

### cURL GET Group Request

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-group.shtml

Use this cURL command to make a GET request for group data. Replace ACCESS_TOKEN with your valid authorization token.

```curl
curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.ecobee.com/1/group?format=json&body={"selection":{"selectionType":"registered"}}'
```

--------------------------------

### Get Runtime Report cURL Request

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-runtime-report.shtml

Use this cURL command to make a GET request to the runtimeReport API. Ensure you replace ACCESS_TOKEN with your valid token.

```curl
curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.ecobee.com/1/runtimeReport?format=json&body=%7B%22startDate%22%3A%222010-01-01%22%2C%22endDate%22%3A%222010-01-02%22%2C%22columns%22%3A%22zoneHvacMode%2CzoneCalendarEvent%22%2C%22selection%22%3A%7B%22selectionType%22%3A%22thermostats%22%2C%22selectionMatch%22%3A%22123456789012%22%7D%7D'
```

--------------------------------

### JavaScript (jQuery) Request Example

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/hierarchy/post-move-thermostat.shtml

This JavaScript code snippet shows how to make a POST request using jQuery to move thermostats. It fetches JSON data from 'json.txt' and sends it to the API endpoint.

```javascript
$.get('json.txt', function(jsonData) {
   alert(JSON.stringify(jsonData));
   $.ajax({
   		beforeSend: function(request) {
        	request.setRequestHeader("Authorization", "Bearer ".concat(ACCESS_TOKEN));
    	},
		type: 'post',
		url: 'https://api.ecobee.com/1/hierarchy/thermostat?format=json',
		dataType: 'json',
		contentType: 'application/json',
		data: JSON.stringify(jsonData),
		success: function (data) {
	   		var response = JSON.stringify(data, null, 4);
	    }
	});
});
```

--------------------------------

### Thermostat Summary Response with Equipment Status

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-thermostat-summary.shtml

This is an example of a response that includes equipment status data. The 'statusList' field provides details on the current operational state of each thermostat's equipment.

```json
{
  "status": {
    "code": 0,
    "message": ""
  },
  "thermostatCount": 3,
  "revisionList": [
    "123456789101:MyStat:true:071223012334:080102000000:080102000000:080102000000",
    "123456789102:Room12:true:071223012334:080102000000:080102000000:080102000000",
    "123456789103::false:071223012334:080102000000:080102000000:080102000000"
  ],
  "statusList": [
    "123456789101:auxHeat1,compCool1",
    "123456789102:auxHeat3,ventilator,humidifier",
    "123456789103:"
  ]
}
```

--------------------------------

### Sample GET Group API Response

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-group.shtml

This is a sample JSON response for the GET Group API call, illustrating the structure of the returned group data and status.

```json
{
  "groups": [
    {
      "groupRef": "3bb5a91b180001",
      "groupName": "ground_floor",
      "synchronizeAlerts": false,
      "synchronizeSystemMode": true,
      "synchronizeSchedule": false,
      "synchronizeQuickSave": false,
      "synchronizeReminders": false,
      "synchronizeContractorInfo": false,
      "synchronizeUserPreferences": false,
      "synchronizeUtilityInfo": false,
      "synchronizeLocation": false,
      "synchronizeReset": true,
      "synchronizeVacation": false,
      "thermostats": [
        "123456789101"
      ]
    },
    {
      "groupRef": "3bb5a91b180000",
      "groupName": "first_floor",
      "synchronizeAlerts": false,
      "synchronizeSystemMode": true,
      "synchronizeSchedule": false,
      "synchronizeQuickSave": false,
      "synchronizeReminders": false,
      "synchronizeContractorInfo": false,
      "synchronizeUserPreferences": false,
      "synchronizeUtilityInfo": false,
      "synchronizeLocation": false,
      "synchronizeReset": true,
      "synchronizeVacation": false,
      "thermostats": [
        "123456789102"
      ]
    }
  ],
  "status": {
    "code": 0,
    "message": ""
  }
}
```

--------------------------------

### Making Requests - Utility

Source: https://www.ecobee.com/home/developer/api/documentation/v1/auth/auth-intro.shtml

Endpoints for managing demand response programs.

```APIDOC
## Utility Endpoints

### GET List Demand Response

**Description**: Retrieves a list of active demand response programs.

**Method**: GET

**Endpoint**: `/utility/demandresponse`

### POST Issue Demand Response

**Description**: Issues a demand response event.

**Method**: POST

**Endpoint**: `/utility/demandresponse/issue`

**Request Body**:
- **programId** (string) - Required - The ID of the demand response program.
- **startTime** (string) - Required - The start time of the event (ISO 8601 format).
- **endTime** (string) - Required - The end time of the event (ISO 8601 format).

### POST Cancel Demand Response

**Description**: Cancels an active demand response event.

**Method**: POST

**Endpoint**: `/utility/demandresponse/cancel`

**Request Body**:
- **programId** (string) - Required - The ID of the demand response program.
```

--------------------------------

### POST Create Runtime Report Job

Source: https://www.ecobee.com/home/developer/api/documentation/v1/request-response.shtml

Initiates a job to generate a runtime report.

```APIDOC
## POST Create Runtime Report Job

### Description
Initiates a job to generate a runtime report.

### Method
POST

### Endpoint
/batch/report/runtime

### Parameters
#### Request Body
- **startDate** (string) - Required - The start date for the report (YYYY-MM-DD).
- **endDate** (string) - Required - The end date for the report (YYYY-MM-DD).
- **thermostatIds** (array) - Optional - A list of thermostat identifiers to include in the report. If omitted, includes all thermostats.

### Request Example
```json
{
  "startDate": "2023-10-01",
  "endDate": "2023-10-26",
  "thermostatIds": ["abcdef1234567890"]
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The identifier for the report generation job.

#### Response Example
```json
{
  "jobId": "reportJob456"
}
```
```

--------------------------------

### Example Response for Runtime Report Job Status

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-list-runtime-report-job.shtml

This is a sample JSON response when retrieving runtime report job statuses. It includes a list of jobs, each with its ID and status, and potentially file links for completed jobs. An overall status code and message are also provided.

```JSON
{
  "jobs": [
    {
      "jobId": "123",
      "status": "queued"
    },
    {
      "jobId": "234",
      "status": "cancelled"
    },
    {
      "jobId": "345",
      "status": "completed",
      "files": [
        "https://s3.amazonaws.com/ecobee-utl/example_dir/examplefile-1.tar.gz.gpg"
      ]
    },
    {
      "jobId": "456",
      "status": "error",
      "message": "Error occured while trying to encrypt bundle."
    }
  ],
  "status": {
    "code": 0,
    "message": ""
  }
    
}
```

--------------------------------

### cURL Request to Get Demand Response List

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-list-demand-response.shtml

Use this cURL command to make a GET request to the demandResponse endpoint. Replace ACCESS_TOKEN with your valid authorization token.

```cURL
curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.ecobee.com/1/demandResponse?format=json&body=\{"operation":"list"\}'
```

--------------------------------

### Add Hierarchy User cURL Example

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/hierarchy/post-add-user.shtml

This cURL command demonstrates how to send a POST request to add a hierarchy user. It includes necessary headers and uses a data-urlencode flag for the JSON payload.

```curl
curl -s --request POST --data-urlencode @json.txt -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer ACCESS_TOKEN" "https://api.ecobee.com/1/hierarchy/user?format=json"
```

--------------------------------

### Export Public PGP Key

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/getting-started-runtime-report-job.shtml

After generating your PGP keys, use this command to display your public key in armor format. This public key needs to be submitted to the ecobee Developer Relations team.

```bash
gpg --armor --export
```

--------------------------------

### Thermostat Summary Response

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-thermostat-summary.shtml

This is an example of a successful response when requesting thermostat summary data. It includes the status, total thermostat count, and a list of thermostat revisions.

```json
{
  "status": {
    "code": 0,
    "message": ""
  },
  "thermostatCount": 3,
  "revisionList": [
    "123456789101:MyStat:true:071223012334:080102000000:080102000000",
    "123456789102:Room12:true:071223012334:080102000000:080102000000",
    "123456789103::false:071223012334:080102000000:080102000000"
  ]
}
```

--------------------------------

### Get Runtime Report JavaScript AJAX Request

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-runtime-report.shtml

This JavaScript snippet demonstrates how to make an AJAX GET request to the runtimeReport API using jQuery. Replace ACCESS_TOKEN with your valid token.

```javascript
$.ajax({
    beforeSend: function(request) {
        request.setRequestHeader("Authorization", "Bearer ".concat(ACCESS_TOKEN));
    },
    dataType: "json",
    url: 'https://api.ecobee.com/1/runtimeReport?format=json&body=%7B%22startDate%22%3A%222010-01-01%22%2C%22endDate%22%3A%222010-01-02%22%2C%22columns%22%3A%22zoneHvacMode%2CzoneCalendarEvent%22%2C%22selection%22%3A%7B%22selectionType%22%3A%22thermostats%22%2C%22selectionMatch%22%3A%22123456789012%22%7D%7D',
    success: function(data) {
    	var response = JSON.stringify(data, null, 4);
    }
});
```

--------------------------------

### Using Management Sets in API Requests

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/hierarchy/getting-started-management-set-hierarchy.shtml

Demonstrates how to use a management set path in an API request to target specific thermostats. This is an alternative to passing a list of thermostat IDs.

```APIDOC
## GET /thermostatSummary

### Description
Retrieves a summary of thermostats, allowing targeting by management set.

### Method
GET

### Endpoint
/1/thermostatSummary

### Parameters
#### Query Parameters
- **json** (string) - Required - A JSON object containing the selection criteria.
  - **selection** (object) - Required - Specifies how to select thermostats.
    - **selectionType** (string) - Required - Must be `managementSet`.
    - **selectionMatch** (string) - Required - The path to the management set (e.g., `/Test Stats`).

### Request Example
```json
{
  "selection": {
    "selectionType": "managementSet",
    "selectionMatch": "/Test Stats"
  }
}
```

### Response
#### Success Response (200)
- **thermostatSummaries** (array) - A list of thermostat summaries matching the selection.

#### Response Example
```json
{
  "thermostatSummaries": [
    {
      "identifier": "exampleThermostatId1",
      "name": "Living Room Thermostat",
      "model": "ecobeeSmartThermostat",
      "lastStatus": {
        "timestamp": "2023-10-27T10:00:00Z",
        "ecobeeRating": 5,
        "weather": {
          "forecastAvg": 22,
          "forecastMin": 18,
          "forecastMax": 26,
          "temp": 21,
          "condition": "clear"
        }
      }
    }
  ]
}
```
```

--------------------------------

### JavaScript GET Group Request

Source: https://www.ecobee.com/home/developer/api/documentation/v1/operations/get-group.shtml

This JavaScript snippet demonstrates how to make a GET request for group data using jQuery's AJAX. Remember to replace ACCESS_TOKEN with your actual token.

```javascript
$.ajax({
    beforeSend: function(request) {
        request.setRequestHeader("Authorization", "Bearer ".concat(ACCESS_TOKEN));
    },
    dataType: "json",
    url: 'https://api.ecobee.com/1/group?format=json&body={"selection":{"selectionType":"registered"}}',
    success: function(data) {
    	var response = JSON.stringify(data, null, 4);
    }
});
```
Tokens:
Raw