openapi: 3.0.3
info:
title: ecobee API
description: >-
The ecobee API is a REST-like JSON interface for reading and controlling
registered ecobee smart thermostats and connected home devices. The data
plane is based at https://api.ecobee.com/1 and returns/accepts JSON. Read
thermostat runtime, settings, sensors, and equipment status with GET
/thermostat, poll for change efficiently with GET /thermostatSummary, and
apply writable properties and thermostat functions with POST /thermostat.
Historical data is available via GET /runtimeReport and GET /meterReport.
Thermostats can be grouped (/group) and, for EMS and Utility accounts,
organized in a management-set hierarchy (/hierarchy/*) and driven with
demand response events (/demandResponse).
Authorization uses OAuth 2.0 with an ecobee PIN flow or the standard
authorization-code flow, plus refresh tokens; the OAuth endpoints
(/authorize and /token) live on the host root https://api.ecobee.com
(without the /1 path). All data-plane requests require an
`Authorization: Bearer ACCESS_TOKEN` header.
NOTE - as of late 2024, ecobee closed its developer program to new API-key
registrations; existing keys continue to function. Endpoint shapes below are
grounded in ecobee's published v1 API documentation; request/response
schemas are simplified models of the documented objects.
version: '1.0'
contact:
name: ecobee Developer
url: https://www.ecobee.com/home/developer/api/introduction/index.shtml
servers:
- url: https://api.ecobee.com/1
description: ecobee API data plane (v1)
- url: https://api.ecobee.com
description: ecobee OAuth 2.0 authorization host (authorize / token)
security:
- bearerAuth: []
tags:
- name: Thermostat
description: Read thermostat state and poll for changes.
- name: Thermostat Update
description: Update writable properties and run thermostat functions.
- name: Reports
description: Historical runtime and meter reports.
- name: Group
description: Group registered thermostats.
- name: Demand Response
description: Utility demand response events.
- name: Hierarchy
description: EMS/Utility management-set hierarchy of thermostats, sets, and users.
- name: Authorization
description: OAuth 2.0 PIN and authorization-code flows and token refresh.
paths:
/thermostat:
get:
operationId: getThermostats
tags:
- Thermostat
summary: Get thermostats
description: >-
Retrieves a selection of registered thermostats and their requested data
(runtime, settings, program, events, alerts, sensors, and more). The
Selection object in the `json` query parameter determines which
thermostats and which sub-objects are returned.
parameters:
- name: json
in: query
required: true
description: >-
URL-encoded JSON request containing a `selection` object (and optional
`page`) that determines the thermostats and data returned.
schema:
type: string
responses:
'200':
description: The matching thermostats and requested data.
content:
application/json:
schema:
$ref: '#/components/schemas/ThermostatResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: updateThermostats
tags:
- Thermostat Update
summary: Update thermostats and run functions
description: >-
Updates writable thermostat properties and/or executes one or more
thermostat functions against a selection of thermostats. Functions are
applied in the order listed. Accessible by Smart and EMS accounts;
requires the smartWrite scope.
parameters:
- name: format
in: query
required: true
description: Response format. Always `json`.
schema:
type: string
default: json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateThermostatRequest'
responses:
'200':
description: A Status object indicating success or failure.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/ApiError'
/thermostatSummary:
get:
operationId: getThermostatSummary
tags:
- Thermostat
summary: Get thermostat summary
description: >-
Returns a compact revision-list summary for the selected thermostats -
thermostat id, name, connection status, and configuration/alert/runtime/
interval revision timestamps - so callers can detect changes without
re-fetching full thermostat objects. Optionally includes equipment
status. Poll no more frequently than once every three minutes.
parameters:
- name: json
in: query
required: true
description: >-
URL-encoded JSON request containing a `selection` object. Set
`includeEquipmentStatus` to true to also receive equipment status.
schema:
type: string
responses:
'200':
description: Revision list (and optional equipment status) for the selection.
content:
application/json:
schema:
$ref: '#/components/schemas/ThermostatSummaryResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/runtimeReport:
get:
operationId: getRuntimeReport
tags:
- Reports
summary: Get runtime report
description: >-
Retrieves historical five-minute-interval runtime data for a set of
thermostats over a date range. Limited to 25 thermostats and a maximum
31-day period per request.
parameters:
- name: format
in: query
required: true
description: Response format. Always `json`.
schema:
type: string
default: json
- name: body
in: query
required: true
description: >-
URL-encoded JSON request containing `selection`, `startDate`,
`endDate`, `columns`, and optional `startInterval`, `endInterval`,
and `includeSensors`.
schema:
type: string
responses:
'200':
description: The runtime report rows for the selection.
content:
application/json:
schema:
$ref: '#/components/schemas/RuntimeReportResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/meterReport:
get:
operationId: getMeterReport
tags:
- Reports
summary: Get meter report
description: >-
Retrieves meter reading history (energy / metering data) for a set of
thermostats over a bounded date range. Available to EMS and Utility
accounts.
parameters:
- name: format
in: query
required: true
description: Response format. Always `json`.
schema:
type: string
default: json
- name: body
in: query
required: true
description: >-
URL-encoded JSON request containing `selection`, `startDate`,
`endDate`, and the meter `columns` requested.
schema:
type: string
responses:
'200':
description: The meter report rows for the selection.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/group:
get:
operationId: getGroups
tags:
- Group
summary: Get groups
description: >-
Retrieves the Group and grouping data for the thermostats registered to
the user. Accessible by Smart accounts only.
parameters:
- name: json
in: query
required: true
description: URL-encoded JSON request containing a `selection` object.
schema:
type: string
responses:
'200':
description: The groups registered to the user.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: updateGroups
tags:
- Group
summary: Update groups
description: >-
Creates or updates the grouping of the user's thermostats. Accessible by
Smart accounts only.
parameters:
- name: format
in: query
required: true
description: Response format. Always `json`.
schema:
type: string
default: json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupRequest'
responses:
'200':
description: A Status object and the updated groups.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/demandResponse:
get:
operationId: listDemandResponses
tags:
- Demand Response
summary: List demand responses
description: >-
Lists the Demand Response events. Accessible by Utility accounts only.
parameters:
- name: json
in: query
required: true
description: URL-encoded JSON request containing the query selection.
schema:
type: string
responses:
'200':
description: The list of demand response events.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: issueDemandResponse
tags:
- Demand Response
summary: Issue or cancel a demand response
description: >-
Issues a Demand Response event to a set of thermostats to adjust their
program, or cancels a previously issued event (via a cancel demand
response request body). Accessible by Utility accounts only.
parameters:
- name: format
in: query
required: true
description: Response format. Always `json`.
schema:
type: string
default: json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DemandResponseRequest'
responses:
'200':
description: A Status object with the demand response reference.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/hierarchy/thermostat:
post:
operationId: hierarchyThermostat
tags:
- Hierarchy
summary: Register, unregister, move, or assign thermostats
description: >-
Registers one or more thermostats with the hierarchy and optionally
assigns them to a management set, or unregisters, moves, or assigns
existing thermostats. The `operation` field selects the action.
Accessible by EMS and Utility accounts only.
parameters:
- name: format
in: query
required: true
description: Response format. Always `json`.
schema:
type: string
default: json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HierarchyThermostatRequest'
responses:
'200':
description: A Status object indicating success or failure.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/hierarchy/set:
get:
operationId: listHierarchySets
tags:
- Hierarchy
summary: List management sets
description: >-
Lists the management sets in the account hierarchy. Accessible by EMS and
Utility accounts only.
parameters:
- name: json
in: query
required: true
description: URL-encoded JSON request containing the set query.
schema:
type: string
responses:
'200':
description: The management sets.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: manageHierarchySet
tags:
- Hierarchy
summary: Add, remove, rename, or move a management set
description: >-
Adds, removes, renames, or moves a management set. The `operation` field
selects the action. Accessible by EMS and Utility accounts only.
parameters:
- name: format
in: query
required: true
description: Response format. Always `json`.
schema:
type: string
default: json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HierarchySetRequest'
responses:
'200':
description: A Status object indicating success or failure.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/hierarchy/user:
get:
operationId: listHierarchyUsers
tags:
- Hierarchy
summary: List hierarchy users
description: >-
Lists the users in the account hierarchy. Accessible by EMS and Utility
accounts only.
parameters:
- name: json
in: query
required: true
description: URL-encoded JSON request containing the user query.
schema:
type: string
responses:
'200':
description: The hierarchy users.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: manageHierarchyUser
tags:
- Hierarchy
summary: Add, update, remove, or unregister a hierarchy user
description: >-
Adds, updates, removes, or unregisters a user in the hierarchy. The
`operation` field selects the action. Accessible by EMS and Utility
accounts only.
parameters:
- name: format
in: query
required: true
description: Response format. Always `json`.
schema:
type: string
default: json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HierarchyUserRequest'
responses:
'200':
description: A Status object indicating success or failure.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/authorize:
servers:
- url: https://api.ecobee.com
description: ecobee OAuth 2.0 authorization host
get:
operationId: authorize
tags:
- Authorization
summary: Begin authorization (PIN or authorization code)
description: >-
Starts an authorization flow. For the ecobee PIN flow, set
`response_type=ecobeePin`; the response returns a PIN, an authorization
`code`, and expiry, which the user enters in the ecobee web portal to
grant access. For the authorization-code flow, set `response_type=code`
with a `redirect_uri`. This endpoint is on the host root, not under /1.
security: []
parameters:
- name: response_type
in: query
required: true
description: '`ecobeePin` for the PIN flow, or `code` for the authorization-code flow.'
schema:
type: string
enum:
- ecobeePin
- code
- name: client_id
in: query
required: true
description: The application key (API key) for your application.
schema:
type: string
- name: scope
in: query
required: true
description: The requested scope.
schema:
type: string
enum:
- smartRead
- smartWrite
- ems
- name: redirect_uri
in: query
required: false
description: Redirect URI for the authorization-code flow.
schema:
type: string
- name: state
in: query
required: false
description: Opaque value echoed back for the authorization-code flow.
schema:
type: string
responses:
'200':
description: PIN, authorization code, and expiry (PIN flow).
content:
application/json:
schema:
$ref: '#/components/schemas/PinResponse'
/token:
servers:
- url: https://api.ecobee.com
description: ecobee OAuth 2.0 authorization host
post:
operationId: token
tags:
- Authorization
summary: Exchange or refresh tokens
description: >-
Exchanges an authorization code for an access token and refresh token
(`grant_type=ecobeePin` or `authorization_code`), or refreshes an
expired access token (`grant_type=refresh_token`). Parameters are passed
as query string. This endpoint is on the host root, not under /1.
security: []
parameters:
- name: grant_type
in: query
required: true
description: The OAuth grant type.
schema:
type: string
enum:
- ecobeePin
- authorization_code
- refresh_token
- name: code
in: query
required: false
description: The authorization code (for ecobeePin / authorization_code grants).
schema:
type: string
- name: refresh_token
in: query
required: false
description: The refresh token (for the refresh_token grant).
schema:
type: string
- name: client_id
in: query
required: true
description: The application key (API key) for your application.
schema:
type: string
- name: redirect_uri
in: query
required: false
description: Redirect URI (for the authorization_code grant).
schema:
type: string
- name: ecobee_type
in: query
required: false
description: Set to `jwt` to have the API return access tokens as JWTs.
schema:
type: string
responses:
'200':
description: An access token, refresh token, scope, and expiry.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'400':
$ref: '#/components/responses/ApiError'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
OAuth 2.0 access token passed as `Authorization: Bearer ACCESS_TOKEN` on
all data-plane requests to https://api.ecobee.com/1.
responses:
Unauthorized:
description: Missing, invalid, or expired access token.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
ApiError:
description: An API error, described by a Status object.
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
schemas:
Status:
type: object
description: Standard ecobee response status.
properties:
code:
type: integer
description: The status code (0 indicates success).
message:
type: string
StatusResponse:
type: object
properties:
status:
$ref: '#/components/schemas/Status'
Page:
type: object
properties:
page:
type: integer
totalPages:
type: integer
pageSize:
type: integer
total:
type: integer
Selection:
type: object
description: >-
Determines which thermostats and which sub-objects are returned or
acted upon.
required:
- selectionType
properties:
selectionType:
type: string
enum:
- registered
- thermostats
- managementSet
description: How to interpret selectionMatch.
selectionMatch:
type: string
description: >-
Comma-separated thermostat identifiers, a management set path, or an
empty string for all registered thermostats.
includeRuntime:
type: boolean
includeSettings:
type: boolean
includeEvents:
type: boolean
includeSensors:
type: boolean
includeEquipmentStatus:
type: boolean
includeAlerts:
type: boolean
includeProgram:
type: boolean
Thermostat:
type: object
properties:
identifier:
type: string
name:
type: string
thermostatRev:
type: string
isRegistered:
type: boolean
modelNumber:
type: string
brand:
type: string
runtime:
type: object
additionalProperties: true
settings:
type: object
additionalProperties: true
events:
type: array
items:
type: object
additionalProperties: true
remoteSensors:
type: array
items:
type: object
additionalProperties: true
ThermostatResponse:
type: object
properties:
page:
$ref: '#/components/schemas/Page'
thermostatList:
type: array
items:
$ref: '#/components/schemas/Thermostat'
status:
$ref: '#/components/schemas/Status'
ThermostatSummaryResponse:
type: object
properties:
thermostatCount:
type: integer
revisionList:
type: array
description: >-
Colon-separated values per thermostat - identifier, name, connected,
and config/alerts/runtime/interval revision timestamps.
items:
type: string
statusList:
type: array
description: Colon-separated equipment status per thermostat (when requested).
items:
type: string
status:
$ref: '#/components/schemas/Status'
Function:
type: object
description: A thermostat function to execute.
required:
- type
properties:
type:
type: string
description: >-
The function name - e.g. setHold, resumeProgram, sendMessage,
createVacation, deleteVacation, setOccupied, controlPlug,
updateSensor, acknowledge.
params:
type: object
additionalProperties: true
UpdateThermostatRequest:
type: object
required:
- selection
properties:
selection:
$ref: '#/components/schemas/Selection'
thermostat:
$ref: '#/components/schemas/Thermostat'
functions:
type: array
items:
$ref: '#/components/schemas/Function'
RuntimeReportRequest:
type: object
required:
- selection
- startDate
- endDate
- columns
properties:
selection:
$ref: '#/components/schemas/Selection'
startDate:
type: string
format: date
endDate:
type: string
format: date
startInterval:
type: integer
minimum: 0
maximum: 287
default: 0
endInterval:
type: integer
minimum: 0
maximum: 287
default: 287
columns:
type: string
description: CSV string of requested runtime columns.
includeSensors:
type: boolean
default: false
RuntimeReportRow:
type: object
properties:
thermostatIdentifier:
type: string
rowCount:
type: integer
rowList:
type: array
items:
type: string
RuntimeReportResponse:
type: object
properties:
startDate:
type: string
endDate:
type: string
columns:
type: string
reportList:
type: array
items:
$ref: '#/components/schemas/RuntimeReportRow'
status:
$ref: '#/components/schemas/Status'
Group:
type: object
properties:
groupRef:
type: string
groupName:
type: string
thermostats:
type: array
items:
type: string
synchronizeSystemMode:
type: boolean
synchronizeVacation:
type: boolean
GroupRequest:
type: object
required:
- selection
- groups
properties:
selection:
$ref: '#/components/schemas/Selection'
groups:
type: array
items:
$ref: '#/components/schemas/Group'
GroupResponse:
type: object
properties:
groups:
type: array
items:
$ref: '#/components/schemas/Group'
status:
$ref: '#/components/schemas/Status'
DemandResponseRequest:
type: object
required:
- selection
properties:
selection:
$ref: '#/components/schemas/Selection'
demandResponse:
type: object
description: The demand response event definition (name, message, event window, and adjustments).
additionalProperties: true
demandResponseRef:
type: string
description: Reference to a demand response to cancel.
HierarchyThermostatRequest:
type: object
required:
- operation
properties:
operation:
type: string
enum:
- register
- unregister
- move
- assign
setPath:
type: string
thermostats:
type: string
description: Comma-separated thermostat identifiers.
HierarchySetRequest:
type: object
required:
- operation
properties:
operation:
type: string
enum:
- add
- remove
- rename
- move
setPath:
type: string
setName:
type: string
parentPath:
type: string
HierarchyUserRequest:
type: object
required:
- operation
properties:
operation:
type: string
enum:
- add
- update
- remove
- unregister
userName:
type: string
setPath:
type: string
privileges:
type: array
items:
type: string
PinResponse:
type: object
properties:
ecobeePin:
type: string
code:
type: string
description: The authorization code to exchange at /token.
scope:
type: string
expires_in:
type: integer
interval:
type: integer
TokenResponse:
type: object
properties:
access_token:
type: string
token_type:
type: string
expires_in:
type: integer
refresh_token:
type: string
scope:
type: string