192 lines
5.1 KiB
Markdown
192 lines
5.1 KiB
Markdown
# 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:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Remove an entity
|
|
DELETE /api/states/<entity_id>
|
|
```
|
|
|
|
## Example curl Usage
|
|
|
|
```bash
|
|
# 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
|