canonical: https://jentic.com/apis/google.home/google-home

# Google Home

Jentic publishes the only available OpenAPI specification for Google Home, keeping it validated and agent-ready. The Google Home Local API exposes the local HTTP control surface used by the Google Home app to communicate with Google Home and Nest speaker devices on the same network. It covers device discovery, assistant readiness checks, alarms and timers, Bluetooth pairing, network setup, and supported locales and timezones. The endpoints are reverse-engineered from the Home app and require a cast-local-authorization-token retrieved from the Google account that owns the device.

## For AI agents

Read and control Google Home and Nest speakers over the local network: query device info, manage alarms and timers, scan for Bluetooth devices, and trigger setup actions.

## Scope

Does not handle Google Assistant cloud commands, YouTube Music playback, or Nest camera streams - use for local Google Home and Nest speaker control only.

## Capabilities

- Discover Google Home devices on the local network and read their app device ID, supported locales, and timezones
- Inspect the assistant readiness state to decide whether a device can accept voice or cast commands
- List, create, and delete alarms and timers on a specific Google Home or Nest speaker
- Scan for nearby Bluetooth devices and trigger pairing from the speaker side
- Read Wi-Fi network status and trigger setup or saved-network operations during onboarding
- Fetch active media and cast offer state to decide whether a device is currently playing audio

## Use cases

### Local Smart Home Dashboard

Build a local-network dashboard that lists every Google Home and Nest speaker, shows current alarms and timers, and surfaces assistant readiness state. The Google Home Local API is reached over HTTP on the device IP with a cast-local-authorization-token, so the dashboard works without round-tripping through Google's cloud and stays responsive on the LAN.

Example prompt: Discover all Google Home devices on the 192.168.1.0/24 subnet and return a JSON list of each device's app device ID, supported locale, and active alarms.

### Bedtime and Wake Routines

Manage alarms and timers on Google Home and Nest speakers programmatically as part of a home automation routine. The local alarms endpoints let an automation set a wake alarm at 06:30, clear leftover timers from yesterday, and confirm the change without depending on the Google Assistant cloud.

Example prompt: Create a 06:30 weekday alarm on the bedroom Google Home Mini and delete any existing alarms scheduled before that time.

### Bluetooth Pairing Helper

Trigger Bluetooth scans and pairing flows on a Google Home speaker from another device. This is useful for headless setup or for home automation routines that need to pair a phone or wearable with a specific speaker without using the Home app UI.

Example prompt: Initiate a Bluetooth scan on the living room Google Home and return the list of nearby devices with signal strength.

### AI Agent Local Smart Home Control

An AI agent running on a home server uses the Google Home Local API through Jentic to read speaker state, check assistant readiness, and adjust alarms in response to natural language commands. Jentic stores the cast-local-authorization-token securely and exposes typed operations so the agent never has to parse the unofficial documentation directly.

Example prompt: When the user says 'cancel my morning alarm', look up the bedroom Google Home, list alarms scheduled before 09:00, and delete the first matching alarm.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/setup/get_app_device_id` | Get the app device ID of a Google Home |
| GET | `/setup/supported_timezones` | List supported timezones on the device |
| GET | `/setup/supported_locales` | List supported locales on the device |
| GET | `/setup/assistant/check_ready_status` | Check whether the assistant is ready to accept commands |
| GET | `/setup/offer` | Read the current cast offer and active media state |

## Key resources

- **Device Info** — Read the app device ID, supported locales, and timezones for a Google Home or Nest speaker
- **Assistant** — Check the assistant ready status before sending voice or cast commands
- **Alarms and Timers** — List, create, and delete alarms and timers on a specific speaker
- **Bluetooth** — Scan for nearby Bluetooth devices and trigger pairing from the speaker
- **Setup and Network** — Read Wi-Fi network status and trigger setup or saved-network operations

## Why Jentic

- **Setup:** Wiring Google Home local control by hand means passing the cast-local-authorization-token header to the device's local setup endpoint, rotating that token, and mapping the setup and readiness endpoints yourself. Through Jentic you install once, import Google Home from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Google Home local control works through top-level setup endpoints rather than a resource id in the URL path, so scope the agent to the operations it needs, such as reading the device id or checking assistant readiness. You choose the operations it may call, so it stays limited to the setup reads you allow.
- **Credential handling:** Your cast-local-authorization-token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check google home ready status' or 'get the local device id', and Jentic returns the matching local operation with its input schema so the agent calls the right endpoint without reading the local API documentation.

## Related APIs

- **Smart Device Management API** — Google's official cloud API for Nest cameras, thermostats, and doorbells
- **HomeGraph API** — Google's HomeGraph API for syncing smart home device state with the Google Assistant
- **OpenHue API** — Open spec for controlling Philips Hue lights and bridges locally
- **Honeywell Home API** — Honeywell's cloud API for thermostats and home sensors

## FAQ

### Why is there no official OpenAPI spec for Google Home?

Google does not publish an OpenAPI specification for the Google Home Local API - it is an undocumented surface used by the Home app. Jentic generates and maintains this spec from the GHLocalApi reverse-engineering project so that AI agents and developers can call Google Home 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 Google Home Local API use?

Each request must include a cast-local-authorization-token header bound to the Google account that set up the speaker. The token is short-lived and must be refreshed via Google's account services. Jentic stores the token in its encrypted vault and injects it at request time so the raw value never enters the agent's context.

### Can I set alarms on a Google Home speaker through this API?

Yes. The `/setup/assistant/alarms` endpoints let you list existing alarms and create or delete entries on a specific device, and `/setup/assistant/timers` covers the equivalent timer operations. Each call targets one device by IP, so the agent must first discover the speaker on the local network.

### What are the rate limits for the Google Home Local API?

Google does not publish rate limits for the local API because it is intended to be reached over the LAN by a single Home app instance. In practice, polling more than once every few seconds per device can cause the speaker to drop the connection, so back off after any 5xx response.

### How do I list alarms on a Google Home speaker through Jentic?

Run jentic search 'list google home alarms', load the returned operation schema, and execute it with the device's local IP and the stored cast-local-authorization-token. The agent receives a typed list of alarm objects with fire time, recurrence, and ID, ready to be used in subsequent delete or update calls.

### Does the API work over the internet or only on the local network?

The Google Home Local API only responds on the same LAN as the speaker - port 8443 on the device's IP. It is not reachable from the public internet, so any agent using it must run on a host inside the home network or via a VPN tunnel.

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

Yes. Because Google Home local control runs through top-level setup endpoints rather than a resource id in the URL path, you scope the agent by choosing exactly which operations it may call from your own self-hosted Jentic One instance, guided by your own rules. You can, for example, allow only read operations like getting the app device ID or checking assistant readiness while withholding the alarm and timer create and delete calls. The cast-local-authorization-token is stored once and injected at execution time, so the agent only ever exercises the operations and credentials you permit.