Home Assistant REST API

Connection

Base URL: http://<HA_IP>:8123/api/
Auth header: Authorization: Bearer <TOKEN>
Token: Generate at http://<HA_IP>:8123/profile → Long-Lived Access Tokens
Response format: JSON (except /api/error_log which is plaintext)

Store token in env var, never hardcode:

export HA_TOKEN="your_token_here"
export HA_URL="http://<HA_IP>:8123"

Status Codes

Code	Meaning
200	Success (existing resource)
201	Created (new resource)
400	Bad request
401	Unauthorized
404	Not found
405	Method not allowed

GET Endpoints

# Health check
GET /api/

# Current HA configuration
GET /api/config

# Loaded components
GET /api/components

# All entity states
GET /api/states

# Specific entity state
GET /api/states/<entity_id>

# Available services
GET /api/services

# Available events
GET /api/events

# Error log (plaintext)
GET /api/error_log

# Camera image
GET /api/camera_proxy/<camera_entity_id>

# All calendar entities
GET /api/calendars

# Calendar events (start and end are required ISO timestamps)
GET /api/calendars/<calendar_entity_id>?start=<ISO>&end=<ISO>

# Historical state changes
GET /api/history/period/<ISO_timestamp>?filter_entity_id=<entity_id>
# Optional params: end_time, minimal_response, no_attributes, significant_changes_only

# Logbook entries
GET /api/logbook/<ISO_timestamp>
# Optional params: entity=<entity_id>, end_time=<ISO>

POST Endpoints

# Create or update entity state (virtual, not device)
POST /api/states/<entity_id>
{"state": "on", "attributes": {"brightness": 255}}

# Fire an event
POST /api/events/<event_type>
{"optional": "event_data"}

# Call a service
POST /api/services/<domain>/<service>
{"entity_id": "light.living_room"}

# Call service and get its response
POST /api/services/<domain>/<service>?return_response
{"entity_id": "..."}

# Render a Jinja2 template
POST /api/template
{"template": "{{ states('sensor.temperature') }}"}

# Validate configuration
POST /api/config/core/check_config

# Handle an intent
POST /api/intent/handle
{"name": "HassTurnOn", "data": {"name": "lights"}}

DELETE Endpoints

# Remove an entity
DELETE /api/states/<entity_id>

Example curl Usage

# Health check
curl -s -H "Authorization: Bearer $HA_TOKEN" $HA_URL/api/

# Get all states
curl -s -H "Authorization: Bearer $HA_TOKEN" $HA_URL/api/states | jq .

# Get specific entity
curl -s -H "Authorization: Bearer $HA_TOKEN" $HA_URL/api/states/light.living_room

# Turn on a light
curl -s -X POST \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "light.living_room"}' \
  $HA_URL/api/services/light/turn_on

# Render template
curl -s -X POST \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "{{ states(\"sensor.temperature\") }}"}' \
  $HA_URL/api/template

Devices

Lights

4x Zigbee Tuya lights (TZ3210 TS0505B):

light.tz3210_r5afgmkl_ts0505b (G2)
light.tz3210_r5afgmkl_ts0505b_g2 (G22)
light.tz3210_r5afgmkl_ts0505b_2
light.tz3210_r5afgmkl_ts0505b_3

Support: color_temp (2000-6535K), xy color mode, brightness (0-254)

Vacuum Cleaner

Entity: vacuum.xiaomi_ru_1173505785_ov71gl (Петя Петя) Status: Docked Type: Xiaomi robot vacuum with mop

Rooms (from sensor.xiaomi_ru_1173505785_ov71gl_room_information_p_2_16):

ID 4: Спальня (Bedroom)
ID 3: Гостиная (Living Room)
ID 5: Кухня (Kitchen)
ID 6: Прихожая (Hallway)
ID 7: Ванная комната (Bathroom)

Services:

vacuum.start — Start cleaning
vacuum.pause — Pause
vacuum.stop — Stop
vacuum.return_to_base — Dock
vacuum.clean_spot — Clean spot
vacuum.set_fan_speed — Set fan (param: fan_speed)
vacuum.send_command — Raw command (params: command, params)
Room-aware: start_vacuum_room_sweep, start_zone_sweep, get_room_configs, set_room_clean_configs

Key attributes:

sensor.xiaomi_ru_1173505785_ov71gl_room_information_p_2_16 — Room data (JSON)
sensor.xiaomi_ru_1173505785_ov71gl_zone_ids_p_2_12 — Zone IDs
button.xiaomi_ru_1173505785_ov71gl_auto_room_partition_a_10_5 — Auto-detect room boundaries

Water Leak Sensors

3x HOBEIAN ZG-222Z Zigbee moisture sensors:

binary_sensor.hobeian_zg_222z — Kitchen
binary_sensor.hobeian_zg_222z_2 — Bathroom
binary_sensor.hobeian_zg_222z_3 — Laundry

Battery sensors: sensor.hobeian_zg_222z_battery, _2, _3

Automations (push to Zabbix via rest_command):

"Water Leak Alert" (water_leak_alert) — any sensor ON → rest_command.zabbix_water_leak with room name
"Water Leak Clear" (water_leak_clear) — all sensors OFF → rest_command.zabbix_water_leak_clear

Notes

POST /api/states/<entity_id> creates a virtual state representation only — it does NOT control physical devices. Use POST /api/services/... for actual device control.
Timestamp format: YYYY-MM-DDThh:mm:ssTZD (ISO 8601)
Using ?return_response on a service that doesn't support it returns a 400 error

5.1 KiB Raw Blame History