Agent-ready OpenAPI document · curated by JenticIOTHome Automationoauth216 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Control ecobee smart thermostats - adjust temperature, read sensor data, pull energy reports, manage thermostat groups, and participate in demand response programs.
Use for: I need to set the thermostat to 72 degrees Fahrenheit, I want to check the current temperature and humidity in my home, Get the energy usage report for the past billing cycle, List all thermostats registered to my account
Not supported: Does not handle HVAC equipment installation, refrigerant management, or ductwork control - use for cloud-based thermostat interaction and energy reporting only.
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.
Install Jentic One Beta
Connect the ecobee API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the ecobee API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fecobee.com%2Fecobee" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fecobee.com%2Fecobee" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with ecobee API.
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
Patterns agents use ecobee API for, with concrete tasks.
★ 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.
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.
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.
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.
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
16 endpoints — jentic publishes the only available openapi specification for ecobee api, keeping it validated and agent-ready.
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
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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
E
ecobee API
- AI-Aware (A-)71/100
78
Foundational Compliance63
Developer Experience & Jentic Compatibility51
AI-Readiness & Agent Experience94
Agent Usability90
Security100
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
78
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: A-Signals: 4
98%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
100%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
14%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
63
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: B-Signals: 4
0%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
50%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
51
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: C-Signals: 4
47%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
100%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
59%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
90
Security
Trust, risk posture, and security compliance.
Grade: A+Signals: 1
90%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
100
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A+Signals: 1
100%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using ecobee API through Jentic.
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.
GET STARTED