canonical: https://jentic.com/apis/ecobee.com/ecobee

# ecobee API

Jentic publishes the only available OpenAPI specification for ecobee API, keeping it validated and agent-ready. Control and monitor ecobee smart thermostats through 16 endpoints covering thermostat state retrieval and updates, energy usage reports, runtime analytics, demand response program participation, thermostat group management, and multi-property management sets. The API uses OAuth 2.0 authorization code flow with the smartWrite scope for full read-write thermostat access.

## For AI agents

Control ecobee smart thermostats - adjust temperature, read sensor data, pull energy reports, manage thermostat groups, and participate in demand response programs.

## Scope

Does not handle HVAC equipment installation, refrigerant management, or ductwork control - use for cloud-based thermostat interaction and energy reporting only.

## Capabilities

- Read current thermostat state including temperature, humidity, HVAC mode, and occupancy sensor data
- Set thermostat hold temperatures, climate programs, and vacation schedules remotely
- Pull runtime and meter reports for energy consumption analysis over configurable date ranges
- Enroll thermostats in utility demand response events for grid load reduction
- Group multiple thermostats to synchronize settings across zones or properties
- Administer multi-property management sets with user and thermostat assignments

## Use cases

### AI Agent Smart Home Climate Control

AI agents control ecobee thermostats through Jentic's intent search, adjusting temperature and HVAC programs based on occupancy patterns, weather forecasts, or energy pricing signals. An agent searches for 'set thermostat temperature', discovers the POST /thermostat endpoint, and sends a setHold function call with the desired temperature and duration. Jentic handles OAuth 2.0 token refresh and thermostat selection automatically.

Example prompt: Set a temperature hold of 70°F heating and 76°F cooling on thermostat ID 'abc123' for the next 4 hours using the setHold function

### Energy Usage Monitoring and Optimization

Track HVAC energy consumption by pulling meter reports (GET /meterReport) and runtime reports (GET /runtimeReport) that break down daily heating hours, cooling hours, fan runtime, and auxiliary heat usage. These reports enable energy optimization algorithms to identify inefficient patterns - such as excessive auxiliary heat activation - and recommend schedule adjustments that reduce utility costs without sacrificing comfort.

Example prompt: Pull the runtime report for thermostat 'abc123' covering the last 30 days, then calculate total heating hours vs cooling hours and identify days with auxiliary heat usage exceeding 4 hours

### Utility Demand Response Integration

Participate in utility demand response programs by creating and managing demand response events through the POST /demandResponse endpoint. When grid load peaks, utilities signal connected thermostats to temporarily reduce energy consumption. The API enables enrollment, event scheduling, and opt-out management for residential and commercial properties participating in load-shedding programs.

Example prompt: Create a demand response event that raises the cooling setpoint by 3°F for all thermostats in management set 'commercial-01' between 2PM and 6PM today

### Multi-Property Thermostat Management

Administer thermostats across multiple properties using management sets (GET/POST /managementSet) with user and thermostat assignments. Property managers control HVAC settings for apartment buildings, hotel rooms, or office suites from a single API integration. The `/managementSet/thermostat` endpoint handles bulk thermostat assignment, while `/managementSet/users` manages access permissions per property.

Example prompt: List all management sets, add thermostat 'xyz789' to management set 'building-a', then assign user 'manager@example.com' with read-write access to that set

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/thermostat` | Retrieve thermostat state, sensors, and settings |
| POST | `/thermostat` | Update thermostat settings and execute functions |
| GET | `/thermostatSummary` | Get summary status of all thermostats |
| GET | `/runtimeReport` | Pull HVAC runtime analytics by date range |
| GET | `/meterReport` | Get energy meter consumption data |
| POST | `/demandResponse` | Create a demand response event |
| POST | `/group` | Create or update a thermostat group |
| POST | `/managementSet` | Create a management set for multi-property admin |

## Key resources

- **Thermostats** — Read state, set temperatures, configure programs, and execute hold/resume functions
- **Reports** — Runtime and meter reports for energy consumption and HVAC usage analytics
- **Demand Response** — Create and manage utility demand response events for grid load reduction
- **Groups** — Synchronize thermostat settings across zones by grouping devices
- **Management Sets** — Multi-property administration with user and thermostat assignments

## Why Jentic

- **Setup:** Wiring the ecobee API by hand means implementing its OAuth 2.0 authorization-code flow with the smartWrite scope, refreshing tokens, and matching ecobee's function-based request pattern against the api.ecobee.com host. Through Jentic you install once, import the ecobee API from the API Directory, store the ecobee OAuth credentials once, and your agent calls it.
- **Permission scoping:** The ecobee API takes the thermostat selection in the request body rather than a URL path id, so scope it by operation: you limit the agent to the operations it needs, such as reading thermostat status and setting a hold, and leave demand-response or management-set calls out unless you add them. The rule constrains what the agent can do, not which single thermostat it names.
- **Credential handling:** Your ecobee OAuth tokens are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'set a thermostat temperature' or 'get an ecobee runtime report', and Jentic returns the matching ecobee operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Particle Cloud API** — IoT device platform for custom sensors that extend smart home monitoring beyond thermostats
- **Samsara API** — Industrial IoT and fleet management for commercial buildings and vehicle HVAC
- **Golioth API** — MCU IoT platform for custom HVAC sensors and control hardware development

## FAQ

### Why is there no official OpenAPI spec for ecobee API?

ecobee does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call ecobee API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the ecobee API use?

The ecobee API uses OAuth 2.0 authorization code flow. Users authorize applications at https://api.ecobee.com/authorize and tokens are exchanged at https://api.ecobee.com/token. The smartWrite scope grants full read-write access to thermostat data. Through Jentic, OAuth tokens are stored in your encrypted Jentic One instance with automatic refresh handling.

### Can I set a specific temperature on my thermostat through this API?

Yes. Send a POST request to /thermostat with a setHold function specifying the desired heat and cool setpoints, hold type (nextTransition, indefinite, or holdHours), and the thermostat identifier in the selection object. For example, set holdType to 'holdHours' with holdHours of 4 to maintain 72°F for 4 hours before resuming the normal schedule.

### How do I get energy usage data through Jentic?

Search Jentic for 'get thermostat energy usage report' to discover the GET /runtimeReport and GET /meterReport endpoints. The runtime report breaks down daily HVAC operation by heating, cooling, fan, and auxiliary heat hours. The meter report provides actual energy consumption data. Both accept startDate and endDate parameters for custom date ranges.

### What sensor data is available from ecobee thermostats?

The GET /thermostat endpoint returns data from all connected sensors including the built-in thermostat sensor and any remote room sensors. Available readings include temperature, humidity, and occupancy (motion detection). Specify 'includeSensors' in the selection to receive the full remoteSensors array with per-sensor capability readings.

### Can I manage thermostats across multiple properties?

Yes. The management set endpoints (GET/POST /managementSet) enable multi-property administration. Create management sets to group thermostats by building or zone, assign users with specific access levels via POST `/managementSet/user`, and add or remove thermostats via POST `/managementSet/thermostat.` This supports commercial property management at scale.

### Can I limit what my agent is allowed to do with the ecobee API?

Yes. Because you run Jentic One yourself, your own rules decide which ecobee operations and credentials the agent may use, and the ecobee API takes the thermostat selection in the request body rather than a URL path, so you scope access by operation. You can allow the agent only the calls it needs, such as reading thermostat state with GET /thermostat and setting a temperature hold with POST /thermostat, while leaving demand-response (POST /demandResponse) and management-set (POST /managementSet) operations out unless you explicitly grant them. Your stored ecobee OAuth credentials are injected at execution time and never enter the agent's prompt or logs.