claude-sync/projects/-Users-csader/memory/reference_ha_api_access.md

name, description, type

name	description	type
Home Assistant API access patterns	How to query HA automations, entity registry, history, and other data not available via MCP tools	reference

The HA MCP tools (mcp__home-assistant__*) cover device control, entity states, and live context — but NOT automations, entity registry, history, logbook, or traces.

For those, use the HA APIs directly:

• REST API (via curl): http://192.168.86.36:8123/api/... with Bearer token from .mcp.json (home-assistant.headers.Authorization)

  • GET /api/states — all entity states (filter by entity_id prefix for automations, etc.)
  • GET /api/config/automation/config/<id> — full automation config (triggers, conditions, actions) by numeric ID from entity attributes
  • GET /api/history/period/<timestamp>?filter_entity_id=... — historical state changes
  • GET /api/logbook/<timestamp>?entity=... — logbook entries

• WebSocket API (ws://192.168.86.36:8123/api/websocket): needed for entity registry operations

  • config/entity_registry/remove — delete stale/duplicate entities
  • config/entity_registry/list — full entity registry (very large response)
  • Requires websockets Python package (installed on Mac)
  • IMPORTANT: Must set max_size=10*1024*1024 on websockets.connect() — the entity registry response exceeds the default 1MB limit
  • Trace API (/api/trace/<entity_id>): may return non-standard JSON or 404. Wrap in try/except and check raw response before parsing.

• Auth token: Available as $HA_TOKEN env var (set in settings.local.json). Use Bearer $HA_TOKEN in curl, or os.environ['HA_TOKEN'] in Python.

How to apply: When user asks about automations, entity cleanup, or historical data, use these APIs rather than saying the MCP can't do it. Always use these patterns from the main conversation — subagents may not have Bash access.