canonical: https://jentic.com/apis/my.tado.com/tado

# My Tado Tado API

The Tado API is the v2 surface used by the Tado web and mobile apps to manage smart heating and cooling devices in residential homes. It exposes home and zone configuration, current device state, weather at the home location, schedule timetables, and zone overlays that override the active schedule for a defined period. Authenticated users can read home structure, list devices, modify zone setpoints, and inspect each zone's capabilities and current readings.

## For AI agents

Read Tado home structure, zone state, and devices, plus override the heating or cooling schedule for a zone. Returns current temperature readings and zone state across 13 operations.

## Scope

Does not control lighting, security cameras, or non-Tado devices - use for Tado smart heating and cooling zone control only.

## Capabilities

- Read the authenticated user's profile and home memberships
- Describe a home including its zones and connected devices
- List all zones in a home with current state and capabilities
- Set or remove a temperature overlay on a zone to override the schedule
- Read the active schedule timetable and its time blocks for a zone
- Pull weather conditions at the home location for context-aware automations
- Inspect each zone's capabilities including supported temperature range and modes

## Use cases

### Manual Temperature Override from a Voice Assistant

Let a voice assistant set a Tado zone to a specific temperature for a defined period. PUT `/homes/{home}/zones/{zone}/overlay` accepts a setpoint and termination condition (timer, manual, or schedule-aligned), then the zone holds that temperature until the overlay expires. DELETE on the same path returns the zone to its scheduled program in one call.

Example prompt: Call PUT `/homes/{home}/zones/{zone}/overlay` with setting=heating at 21 degrees and termination=TIMER for 7200 seconds, then DELETE the overlay when the user says 'cancel'.

### Energy Usage Dashboard

Build a dashboard that shows current zone temperatures, target setpoints, and weather context to help residents understand heating behavior. The `/homes/{home}/zones`, zone state, and `/homes/{home}/weather` endpoints supply everything needed for a single-screen overview without polling individual devices. The 13-endpoint surface keeps the data model small and easy to refresh.

Example prompt: Refresh every 5 minutes: GET `/homes/{home}/zones`, then GET `/homes/{home}/zones/{zone}/state` for each, plus GET `/homes/{home}/weather`, and render a dashboard tile per zone.

### Schedule Inspection and Audit

Inspect the configured weekly schedule for each Tado zone for compliance audits or energy reviews. The schedule timetable and timetable-blocks endpoints expose the full block-by-block program a zone runs through. Energy and facilities teams use this to flag zones that hold high setpoints overnight or during unoccupied hours.

Example prompt: Pull each zone's active timetable via `/schedule/activeTimetable` and then `/schedule/timetables/{timetable}/blocks` to compute hours per day above 20 degrees.

### Geofencing Boost or Setback

Drive boost-on-arrival or setback-on-departure behavior from an external geofence event source. When the user crosses the geofence, the agent calls the overlay endpoint to bring zones to comfort temperature; on departure it removes the overlay so the schedule resumes. This complements Tado's built-in geofencing for households that drive automation from a different presence source.

Example prompt: On geofence-enter, PUT overlay at 20 degrees with termination=MANUAL on each zone; on geofence-exit, DELETE the overlay so the schedule resumes.

### AI Agent Smart Home Assistant

Equip a Jentic-driven home assistant with Tado control as one of its tools. The agent searches Jentic for 'set Tado zone temperature', loads PUT `/homes/{home}/zones/{zone}/overlay`, and calls it in response to user requests. Jentic handles the OAuth 2.0 flow so the agent never sees the user's Tado credentials.

Example prompt: Through Jentic, search for 'override Tado zone temperature', load the overlay endpoint, and set the bedroom to 19 degrees until the next schedule change.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/me` | Get the authenticated user's profile |
| GET | `/homes/{home}` | Describe a home |
| GET | `/homes/{home}/zones` | List zones in a home |
| GET | `/homes/{home}/zones/{zone}/state` | Get current state of a zone |
| PUT | `/homes/{home}/zones/{zone}/overlay` | Set a temperature overlay on a zone |
| DELETE | `/homes/{home}/zones/{zone}/overlay` | Remove an overlay and return to schedule |
| GET | `/homes/{home}/weather` | Get weather at home location |

## Key resources

- **Profile** — Read the authenticated user's profile and homes
- **Home** — Describe a home and list its installations and devices
- **Zones** — List zones, read state and capabilities, and manage overlays
- **Schedule** — Read the active timetable and its time blocks
- **Weather** — Pull the weather at the home's location

## AI readiness

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.

- **Score:** 52 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 44 / 100
  - Agent Usability: 94 / 100
  - Security: 30 / 100
  - AI Discoverability: 32 / 100
- **View full report:** https://jentic.com/apis/my.tado.com/tado/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Tado API by hand means running its OAuth 2.0 password flow against the token endpoint, refreshing tokens, and threading home and zone ids through each heating call yourself. Through Jentic you install once, import the Tado API from the API Directory, complete the OAuth grant once, and your agent calls it.
- **Permission scoping:** Tado puts the home and zone ids in the URL path (`/homes/{home}/zones/{zone}/...`), so a rule can pin your agent to one zone: it can read that zone's state and nothing else. You choose the operations it may call, so a call like setting or clearing the overlay is not included unless you add it.
- **Credential handling:** Your Tado OAuth grant is stored once, encrypted, by your own Jentic One instance, refreshed automatically, and injected at execution time. The tokens never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'set tado temperature' or 'list heating zones', and Jentic returns the matching Tado operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Ecobee API** — Ecobee is a US-focused smart thermostat with its own developer API covering zone control and reporting.
- **Honeywell Home API** — Honeywell Home covers Honeywell-branded thermostats and smart home devices as another zone-control alternative.
- **OpenHue API** — OpenHue controls Philips Hue lighting, complementing Tado heating in a single home automation flow.

## FAQ

### What authentication does the Tado API use?

Tado uses OAuth 2.0. The user authenticates with their Tado account and the resulting access token is sent on each request. Through Jentic, the OAuth flow is handled in your Jentic One instance and tokens are refreshed automatically, so agent code never holds raw user credentials.

### Can I set a specific temperature with the Tado API?

Yes. PUT `/homes/{home}/zones/{zone}/overlay` accepts a setting (heating mode and target temperature) and termination condition. The overlay holds until it expires or until you DELETE it on the same path to return to the schedule.

### How do I remove a manual override through Jentic?

Through Jentic, search for 'remove Tado zone overlay', load DELETE `/homes/{home}/zones/{zone}/overlay`, and call it with the home and zone IDs. Jentic forwards the call with the OAuth access token and the zone returns to its scheduled program.

### What are the rate limits for the Tado API?

Rate limits are not declared in the OpenAPI spec. Tado throttles high-frequency polling at the gateway, so refresh zone state on a 1-5 minute cadence rather than per-second polling, and back off on 429 responses.

### Can I read the weather at my home location?

Yes. GET `/homes/{home}/weather` returns the current weather conditions Tado uses for its own automation. This is useful for context-aware rules like 'do not preheat if outside is already warm enough'.

### Does the Tado API expose schedule timetables?

Yes. GET `/homes/{home}/zones/{zone}/schedule/activeTimetable` returns the active timetable and GET `/homes/{home}/zones/{zone}/schedule/timetables/{timetable}/blocks` returns its block-by-block program. Read these together for full audit visibility.

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

Yes. Because you self-host Jentic One, your own rules decide which Tado operations and credentials the agent may use. Since Tado puts the home and zone ids in the URL path, you can pin the agent to a single zone and allow only read calls like GET `/homes/{home}/zones/{zone}/state`, so it sees that zone's state and nothing more. Write operations such as PUT or DELETE on `/homes/{home}/zones/{zone}/overlay` are excluded unless you explicitly add them.