ha-api-access

name	ha-api-access
description	Access the Home Assistant REST API using environment variables HA_URL and HA_TOKEN exported in ~/.zshrc. Use when: (1) need to query Home Assistant entity states, (2) need to call HA services programmatically, (3) need to debug or inspect HA integration state, (4) user asks to interact with their Home Assistant instance. Covers authentication, common endpoints, and usage patterns.
author	Claude Code
version	1.0.0
date	"2026-02-19T00:00:00.000Z"

Home Assistant API Access

Problem

Need to interact with the user's Home Assistant instance from the CLI for debugging, testing, or inspecting integration state.

Context / Trigger Conditions

• User asks to check HA entity states or services
• Need to debug a custom integration by inspecting live state
• Want to call HA services or query the API
• User mentions "HA", "Home Assistant", or "home assistant" API access

Prerequisites

Environment variables are exported in ~/.zshrc:

• HA_URL — Base URL of the HA instance (e.g., http://192.168.1.11:8123)
• HA_TOKEN — Long-lived access token for authentication

Solution

Verify connection

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/" | python3 -m json.tool

Get all states

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | python3 -m json.tool

Get a specific entity state

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/<entity_id>" | python3 -m json.tool

Call a service

curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  -d '{"entity_id": "<entity_id>"}' \
  "$HA_URL/api/services/<domain>/<service>" | python3 -m json.tool

Get config

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/config" | python3 -m json.tool

Filter states (e.g., area_occupancy entities)

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | \
  python3 -c "import json,sys; [print(json.dumps(e, indent=2)) for e in json.load(sys.stdin) if 'area_occupancy' in e['entity_id']]"

Verification

A successful connection returns {"message": "API running."} with HTTP 200.

Notes

• Always use $HA_URL and $HA_TOKEN env vars — never hardcode credentials
• The token is a long-lived access token created in HA UI under Profile > Security
• Pipe through python3 -m json.tool for readable output
• For large responses, pipe through python3 -c with filtering logic
• The HA REST API docs: https://developers.home-assistant.io/docs/api/rest/