openapi: 3.0.3
info:
  title: ecobee Authorization Thermostat 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.
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'
  /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'
components:
  schemas:
    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'
    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
    Page:
      type: object
      properties:
        page:
          type: integer
        totalPages:
          type: integer
        pageSize:
          type: integer
        total:
          type: integer
    StatusResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
    ThermostatResponse:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/Page'
        thermostatList:
          type: array
          items:
            $ref: '#/components/schemas/Thermostat'
        status:
          $ref: '#/components/schemas/Status'
    Status:
      type: object
      description: Standard ecobee response status.
      properties:
        code:
          type: integer
          description: The status code (0 indicates success).
        message:
          type: string
  responses:
    Unauthorized:
      description: Missing, invalid, or expired access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusResponse'
  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.'