home-assistant-api

name	home-assistant-api
description	Interact with a Home Assistant instance through its REST API using curl. Supports reading entity states, controlling smart home devices, calling services for lights, switches, covers, locks, climate, and media players, rendering templates, querying history and logbook data, and firing events. Also supports destructive operations (delete entity, validate config) with mandatory user confirmation. Use when the user asks to check sensors or devices in Home Assistant, turn lights or switches on and off, inspect HA configuration, query automations or entity history, or control smart home devices through the Home Assistant API.
metadata	{"tags":"home assistant, smart home, home automation, sensors, lights, switches, devices, ha, api"}

Home Assistant API Skill

Setup

Two environment variables are required for all operations:

export HA_BASE_URL="http://homeassistant.local:8123"
export HA_TOKEN="<Long-Lived Access Token>"

Obtain a Long-Lived Access Token from: http://<HA_HOST>:8123/profile → scroll to the bottom → "Long-Lived Access Tokens".

Dry-run mode (prints the curl command, no execution):

export HA_DRY_RUN=1

---

Core Workflow

For every task, follow this sequence:

1. Inspect — read relevant state(s) or list available services before acting
2. Execute — run the action using the script
3. Verify — read the state again to confirm the change
4. Summarize — report changed entities and final state to the user

Reference loading rules:

• MANDATORY: load references/safety-rules.md before any destructive or high-impact operation (delete-state, check-config, homeassistant.restart, homeassistant.stop, reload services, or bulk updates).
• Load references/rest-endpoints.md only when command parameters, endpoint behavior, or response format are unclear.
• Do not load references for straightforward read operations where this file already provides enough command guidance.

---

Using the Script

All commands use scripts/ha_rest.sh. Always run from the skill's base directory or with an absolute path.

# Quick examples
./scripts/ha_rest.sh health
./scripts/ha_rest.sh states
./scripts/ha_rest.sh state light.living_room
./scripts/ha_rest.sh call light turn_on '{"entity_id": "light.living_room"}'
./scripts/ha_rest.sh call light turn_off '{"entity_id": "light.kitchen"}'
./scripts/ha_rest.sh call switch turn_on '{"entity_id": "switch.fan"}'
./scripts/ha_rest.sh call cover set_cover_position '{"entity_id": "cover.blinds", "position": 50}'
./scripts/ha_rest.sh render-template '{{ states("sensor.temperature") }}'
./scripts/ha_rest.sh history sensor.temperature

For destructive operations, always get explicit user confirmation first, then pass --confirm:

./scripts/ha_rest.sh delete-state sensor.old_entity --confirm
./scripts/ha_rest.sh check-config --confirm

---

Safety Rules

Read references/safety-rules.md for the full decision table. Summary:

• No confirmation needed: all GET operations, all normal service calls (turn on/off, set position, etc.), set-state, fire-event, render-template
• Confirmation REQUIRED: delete-state, check-config
• Confirmation REQUIRED (judgment): homeassistant.restart, homeassistant.stop, automation.reload, script.reload, and any config-mutating service call

For bulk actions affecting multiple entities, list all affected entities and confirm the scope with the user before executing.

NEVER:

• NEVER run homeassistant.restart or homeassistant.stop without explicit user confirmation and impact scope.
• NEVER execute reload services (automation.reload, script.reload) during active troubleshooting without stating expected side effects.
• NEVER perform multi-entity write actions from wildcard assumptions; enumerate target entity IDs first.
• NEVER skip post-action verification for state-changing operations.

---

Endpoint Reference

For detailed endpoint docs, parameters, and response shapes, see references/rest-endpoints.md.

Failure Fallback Matrix

If this fails	Try this next	Reason
./scripts/ha_rest.sh state <entity_id> returns not found	Run ./scripts/ha_rest.sh states and locate the correct entity ID	Entity IDs are exact and often renamed by integrations
Service call returns validation error	Run ./scripts/ha_rest.sh services and verify exact domain/service signature	Available services and payload shapes vary by instance
History query is empty	Expand time window and verify entity has recorder/history enabled	Recorder filters can omit domains/entities
Template render fails	Start with a minimal template, then incrementally add logic	Isolates Jinja syntax errors quickly

Key quick reference:

Task	Script command
Is HA reachable?	./scripts/ha_rest.sh health
List all entities	./scripts/ha_rest.sh states
Read entity state	./scripts/ha_rest.sh state <entity_id>
Control a device	./scripts/ha_rest.sh call <domain> <service> '<json>'
State history	./scripts/ha_rest.sh history <entity_id> [start] [end]
Recent logbook	./scripts/ha_rest.sh logbook [entity_id]
Render template	./scripts/ha_rest.sh render-template '<jinja2>'
List services	./scripts/ha_rest.sh services
Delete entity (⚠)	./scripts/ha_rest.sh delete-state <entity_id> --confirm
Validate config (⚠)	./scripts/ha_rest.sh check-config --confirm

---

Common Service Domains

Domain	Common services
light	turn_on, turn_off, toggle
switch	turn_on, turn_off, toggle
cover	open_cover, close_cover, stop_cover, set_cover_position
lock	lock, unlock
climate	set_temperature, set_hvac_mode, turn_on, turn_off
media_player	media_play, media_pause, media_stop, volume_set
automation	trigger, turn_on, turn_off, reload
script	turn_on, reload
scene	turn_on
input_boolean	turn_on, turn_off, toggle
input_number	set_value
homeassistant	restart ⚠, stop ⚠

Use ./scripts/ha_rest.sh services to discover exact available services on the user's HA instance.