ecobee

opencollection: 1.0.0
info:
  name: ecobee API
  version: '1.0'
  description: 'REST-like JSON API for reading and controlling registered ecobee smart thermostats. Data plane base URL: https://api.ecobee.com/1
    (Bearer access token). OAuth authorize/token endpoints are on the host root https://api.ecobee.com. NOTE: ecobee closed
    its developer program to new API-key registrations in late 2024; existing keys still function.'
request:
  auth:
    type: bearer
    token: '{{accessToken}}'
items:
- info:
    name: Thermostat
    type: folder
  items:
  - info:
      name: Get thermostats.
      type: http
    http:
      method: GET
      url: https://api.ecobee.com/1/thermostat?json={"selection":{"selectionType":"registered","selectionMatch":"","includeRuntime":true,"includeSettings":true}}
    docs: Retrieves registered thermostats and their requested data (runtime, settings, events, sensors).
  - info:
      name: Get thermostat summary.
      type: http
    http:
      method: GET
      url: https://api.ecobee.com/1/thermostatSummary?json={"selection":{"selectionType":"registered","selectionMatch":"","includeEquipmentStatus":true}}
    docs: Compact revision-list summary to detect changes without re-fetching full objects. Poll at most once every three
      minutes.
- info:
    name: Thermostat Update
    type: folder
  items:
  - info:
      name: Update thermostat and run functions.
      type: http
    http:
      method: POST
      url: https://api.ecobee.com/1/thermostat?format=json
      body:
        type: json
        data: "{\n  \"selection\": {\n    \"selectionType\": \"thermostats\",\n    \"selectionMatch\": \"THERMOSTAT_ID\"\n\
          \  },\n  \"functions\": [\n    { \"type\": \"setHold\", \"params\": { \"holdType\": \"nextTransition\", \"heatHoldTemp\"\
          : 700, \"coolHoldTemp\": 750 } }\n  ]\n}"
    docs: Updates writable thermostat properties and/or runs thermostat functions. Requires smartWrite scope.
- info:
    name: Reports
    type: folder
  items:
  - info:
      name: Get runtime report.
      type: http
    http:
      method: GET
      url: https://api.ecobee.com/1/runtimeReport?format=json&body={"startDate":"2026-06-01","endDate":"2026-06-07","columns":"zoneAveTemp,compHeat1,compCool1","selection":{"selectionType":"thermostats","selectionMatch":"THERMOSTAT_ID"}}
    docs: Historical five-minute-interval runtime data. Limited to 25 thermostats and a 31-day period per request.
  - info:
      name: Get meter report.
      type: http
    http:
      method: GET
      url: https://api.ecobee.com/1/meterReport?format=json&body={"startDate":"2026-06-01","endDate":"2026-06-07","selection":{"selectionType":"thermostats","selectionMatch":"THERMOSTAT_ID"}}
    docs: Meter reading history for a set of thermostats. EMS and Utility accounts only.
- info:
    name: Group
    type: folder
  items:
  - info:
      name: Get groups.
      type: http
    http:
      method: GET
      url: https://api.ecobee.com/1/group?json={"selection":{"selectionType":"registered","selectionMatch":""}}
    docs: Retrieves the group and grouping data for the user's thermostats. Smart accounts only.
  - info:
      name: Update groups.
      type: http
    http:
      method: POST
      url: https://api.ecobee.com/1/group?format=json
      body:
        type: json
        data: "{\n  \"selection\": { \"selectionType\": \"registered\", \"selectionMatch\": \"\" },\n  \"groups\": [ { \"\
          groupName\": \"Upstairs\", \"thermostats\": [\"THERMOSTAT_ID\"], \"synchronizeVacation\": true } ]\n}"
    docs: Creates or updates the grouping of the user's thermostats. Smart accounts only.
- info:
    name: Demand Response
    type: folder
  items:
  - info:
      name: List demand responses.
      type: http
    http:
      method: GET
      url: https://api.ecobee.com/1/demandResponse?json={"selection":{"selectionType":"managementSet","selectionMatch":"/"}}
    docs: Lists demand response events. Utility accounts only.
  - info:
      name: Issue demand response.
      type: http
    http:
      method: POST
      url: https://api.ecobee.com/1/demandResponse?format=json
      body:
        type: json
        data: "{\n  \"selection\": { \"selectionType\": \"thermostats\", \"selectionMatch\": \"THERMOSTAT_ID\" },\n  \"demandResponse\"\
          : { \"name\": \"Peak Event\", \"message\": \"Utility peak load event\", \"event\": { \"startDate\": \"2026-07-15\"\
          , \"startTime\": \"16:00:00\", \"endDate\": \"2026-07-15\", \"endTime\": \"19:00:00\" } }\n}"
    docs: Issues a demand response event to a set of thermostats. Utility accounts only. Send a cancel body to cancel an event.
- info:
    name: Hierarchy
    type: folder
  items:
  - info:
      name: Register / move / assign thermostats.
      type: http
    http:
      method: POST
      url: https://api.ecobee.com/1/hierarchy/thermostat?format=json
      body:
        type: json
        data: "{\n  \"operation\": \"register\",\n  \"setPath\": \"/Location 1/Group 1\",\n  \"thermostats\": \"THERMOSTAT_ID\"\
          \n}"
    docs: Registers, unregisters, moves, or assigns thermostats in the management-set hierarchy. EMS and Utility accounts
      only.
  - info:
      name: List management sets.
      type: http
    http:
      method: GET
      url: https://api.ecobee.com/1/hierarchy/set?json={"operation":"list"}
    docs: Lists the management sets in the account hierarchy. EMS and Utility accounts only.
  - info:
      name: Add / rename / move set.
      type: http
    http:
      method: POST
      url: https://api.ecobee.com/1/hierarchy/set?format=json
      body:
        type: json
        data: "{\n  \"operation\": \"add\",\n  \"setName\": \"Group 1\",\n  \"parentPath\": \"/Location 1\"\n}"
    docs: Adds, removes, renames, or moves a management set. EMS and Utility accounts only.
  - info:
      name: List users.
      type: http
    http:
      method: GET
      url: https://api.ecobee.com/1/hierarchy/user?json={"operation":"list"}
    docs: Lists the users in the account hierarchy. EMS and Utility accounts only.
  - info:
      name: Add / update / remove user.
      type: http
    http:
      method: POST
      url: https://api.ecobee.com/1/hierarchy/user?format=json
      body:
        type: json
        data: "{\n  \"operation\": \"add\",\n  \"userName\": \"user@example.com\",\n  \"setPath\": \"/Location 1\",\n  \"\
          privileges\": [\"hierarchy\"]\n}"
    docs: Adds, updates, removes, or unregisters a user in the hierarchy. EMS and Utility accounts only.
- info:
    name: Authorization
    type: folder
  items:
  - info:
      name: Authorize (ecobee PIN).
      type: http
    http:
      method: GET
      url: https://api.ecobee.com/authorize?response_type=ecobeePin&client_id={{clientId}}&scope=smartWrite
      auth:
        type: none
    docs: Starts the ecobee PIN flow; returns a PIN, an authorization code, and expiry. The user enters the PIN in the ecobee
      web portal.
  - info:
      name: Token (exchange PIN code).
      type: http
    http:
      method: POST
      url: https://api.ecobee.com/token?grant_type=ecobeePin&code=AUTH_CODE&client_id={{clientId}}
      auth:
        type: none
    docs: Exchanges the authorization code for an access token and refresh token.
  - info:
      name: Token (refresh).
      type: http
    http:
      method: POST
      url: https://api.ecobee.com/token?grant_type=refresh_token&refresh_token={{refreshToken}}&client_id={{clientId}}
      auth:
        type: none
    docs: Refreshes an expired access token using the refresh token.
bundled: true