---
name: home-assistant
description: Interact with a Home Assistant instance via its REST API. Use to query entity states, control devices, and manage automations. Requires HA URL and long-lived access token via environment variables HA_URL and HA_TOKEN.
---

# Home Assistant Skill

This skill enables interaction with a Home Assistant instance through its REST API.

## Configuration

Set these environment variables:
- `HA_URL` - Home Assistant URL (e.g., `http://192.168.0.39:8123` or `https://your-ha.com`)
- `HA_TOKEN` - Long-lived access token from HA Profile > Security > Create Token

## Common Commands

### Get All States
```
GET /api/states
```
Returns all entity states. Useful for overview.

### Get Specific Entity
```
GET /api/states/<entity_id>
```
Example: `/api/states/climate.living_room`

### Control Device (turn_on, turn_off, toggle, etc.)
```
POST /api/services/<domain>/<service>
Body: {"entity_id": "<entity_id>"}
```
Example - turn on a light:
```
POST /api/services/light/turn_on
Body: {"entity_id": "light.kitchen_lights"}
```

### Call Climate Service
```
POST /api/services/climate/set_temperature
Body: {"entity_id": "climate.living_room", "temperature": 72}
```

## API Endpoints Reference

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/states` | GET | All entity states |
| `/api/states/<entity_id>` | GET | Single entity state |
| `/api/config` | GET | HA configuration |
| `/api/history/period/<timestamp>` | GET | State history |
| `/api/logbook/<timestamp>` | GET | Logbook entries |

## Domains

Common domains: `light`, `switch`, `climate`, `cover`, `media_player`, `automation`, `script`, `input_boolean`, `sensor`

## Tips

- Use `/api/states` first to discover entity IDs
- Entity IDs are lowercase with underscores: `light.living_room`
- Services like `turn_on` support additional attributes: `{"entity_id": "light.kitchen", "brightness": 255}`