openapi: 3.0.3
info:
  title: ecobee Authorization Thermostat Update 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 Update
  description: Update writable properties and run thermostat functions.
paths:
  /thermostat:
    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'
components:
  schemas:
    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
    UpdateThermostatRequest:
      type: object
      required:
      - selection
      properties:
        selection:
          $ref: '#/components/schemas/Selection'
        thermostat:
          $ref: '#/components/schemas/Thermostat'
        functions:
          type: array
          items:
            $ref: '#/components/schemas/Function'
    StatusResponse:
      type: object
      properties:
        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
    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'
    ApiError:
      description: An API error, described by a Status object.
      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.'