Google Home API

Tools exposes a permission-gated Google Home integration for Home Graph requests.

Access model

• API routes are under /api/google-home/*
• Requires authenticated user with google-home.use permission (admins are allowed)
• Admin UI console is available at /admin/google-home

Endpoints

POST /api/google-home/request

Generic wrapper for supported Google Home Graph endpoints.

Request body:

{
  "endpoint": "v1/devices:query",
  "payload": {
    "agentUserId": "demo-user",
    "inputs": []
  }
}

POST /api/google-home/devices/query

Convenience endpoint for state queries.

Request body:

{
  "agentUserId": "demo-user",
  "inputs": []
}

POST /api/google-home/devices/request-sync

Convenience endpoint for sync requests.

Request body:

{
  "agentUserId": "demo-user",
  "async": true
}

POST /api/google-home/push/tokens/register

Register/update a mobile push token for the current user.

Request body:

{
  "token": "fcm-device-token",
  "platform": "android",
  "device_label": "Pixel 9"
}

GET /api/google-home/push/tokens

List active push tokens for the current user.

DELETE /api/google-home/push/tokens/{tokenId}

Deactivate a registered push token for the current user.

POST /api/google-home/push/test

Send a test push to all active tokens for the current user.

Request body:

{
  "title": "Tools Google Home",
  "body": "Push notifications are configured and working."
}

Response format

Successful/failed responses follow this envelope:

{
  "ok": true,
  "status": 200,
  "endpoint": "v1/devices:query",
  "data": {},
  "push": {
    "attempted": 1,
    "delivered": 1,
    "ok": true,
    "error": ""
  }
}

If credentials are missing or endpoint is unsupported, ok is false with error and HTTP status.

Configuration

Set credentials in .env:

• GOOGLE_HOME_API_BASE_URL (default https://homegraph.googleapis.com)
• GOOGLE_API_KEY (optional)
• GOOGLE_HOMEGRAPH_BEARER (optional)
• GOOGLE_FCM_SERVER_KEY (for push notifications)
• GOOGLE_FCM_ENDPOINT (default https://fcm.googleapis.com/fcm/send)
• GOOGLE_HOME_TIMEOUT (default 15)

At least one credential (GOOGLE_API_KEY or GOOGLE_HOMEGRAPH_BEARER) must be configured.