openapi: 3.0.3
info:
  title: ecobee Authorization Reports 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: Reports
  description: Historical runtime and meter reports.
paths:
  /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'
components:
  schemas:
    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'
    RuntimeReportRow:
      type: object
      properties:
        thermostatIdentifier:
          type: string
        rowCount:
          type: integer
        rowList:
          type: array
          items:
            type: string
    StatusResponse:
      type: object
      properties:
        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.'