# 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