home-assistant-api

What this skill does

# Home Assistant REST API Orchestration Skill

This skill provides access to the Home Assistant REST API for building integrations, automating smart home devices, and managing Home Assistant instances programmatically.

## Quick Reference: When to Load Which Resource

| Task | Load Resource |
|------|---------------|
| Setting up authentication, understanding API basics, HTTP methods | `resources/core-concepts.md` |
| Querying entity states, updating states, monitoring changes | `resources/state-management.md` |
| Controlling lights, climate, locks, and other devices | `resources/service-reference.md` |
| Understanding light, switch, sensor, climate entity types | `resources/entity-types.md` |
| Server-side template queries, complex filters, aggregations | `resources/templates.md` |
| System configuration, component discovery, error logs | `resources/system-config.md` |
| Complete code examples, client libraries, patterns | `resources/examples.md` |

## Orchestration Protocol

### Phase 1: Task Analysis

Identify what the user needs to accomplish:

**Authentication & Setup?**
- Getting started with Home Assistant API
- Creating or managing tokens
- Configuring HTTP clients
→ Load `resources/core-concepts.md`

**Query or Monitor State?**
- "What is the temperature in the kitchen?"
- "Is the front door locked?"
- "Get all lights that are on"
- "Monitor entity changes"
→ Load `resources/state-management.md`

**Control a Device?**
- "Turn on the kitchen light"
- "Set thermostat to 22°C"
- "Lock the front door"
- "Play music on speaker"
→ Load `resources/service-reference.md` (then find entity type in `resources/entity-types.md`)

**Understand Entity Types?**
- "What attributes does a climate entity have?"
- "What services are available for locks?"
- "How do I control a media player?"
→ Load `resources/entity-types.md`

**Complex Query or Data Aggregation?**
- "Count all lights that are on"
- "Get devices with low battery"
- "Average temperature from all sensors"
- "Conditional logic based on time of day"
→ Load `resources/templates.md`

**System Management or Discovery?**
- "What components are loaded?"
- "What services are available?"
- "Check configuration validity"
- "View error logs"
→ Load `resources/system-config.md`

**Practical Working Example?**
- Code in Python, Node.js, Bash, curl
- Integration patterns
- Error handling
- Multi-entity operations
→ Load `resources/examples.md`

### Phase 2: Endpoint Selection

Use this decision tree to select the right API endpoint:

```
Do you need to...
│
├─ GET INFORMATION?
│  ├─ Get one entity's state?        → GET /api/states/{entity_id}
│  ├─ Get all entity states?         → GET /api/states (then filter)
│  ├─ Get configuration?             → GET /api/config
│  ├─ List available services?       → GET /api/services
│  ├─ Discover event types?          → GET /api/events
│  ├─ Query historical data?         → GET /api/history/period/{timestamp}
│  ├─ Get error log?                 → GET /api/error_log
│  ├─ Complex query/computation?     → POST /api/template
│  └─ Check system status?           → GET /api/
│
├─ CONTROL A DEVICE?
│  ├─ Light (on/off/brightness)?     → POST /api/services/light/{service}
│  ├─ Switch?                        → POST /api/services/switch/{service}
│  ├─ Climate/thermostat?            → POST /api/services/climate/{service}
│  ├─ Lock?                          → POST /api/services/lock/{service}
│  ├─ Cover/blinds?                  → POST /api/services/cover/{service}
│  ├─ Media player?                  → POST /api/services/media_player/{service}
│  ├─ Fan?                           → POST /api/services/fan/{service}
│  ├─ Camera?                        → POST /api/services/camera/{service}
│  └─ Any service?                   → POST /api/services/{domain}/{service}
│
├─ MODIFY STATE (NOT FOR DEVICE CONTROL)?
│  ├─ Create/update state?           → POST /api/states/{entity_id}
│  ├─ Delete state?                  → DELETE /api/states/{entity_id}
│  └─ Fire custom event?             → POST /api/events/{event_type}
│
└─ MANAGE SYSTEM?
   ├─ Validate config?               → POST /api/config/core/check_config
   ├─ Reload config?                 → POST /api/services/homeassistant/reload_core_config
   ├─ Restart Home Assistant?        → POST /api/services/homeassistant/restart
   ├─ Get components list?           → GET /api/components
   ├─ Update entity metadata?        → POST /api/services/homeassistant/update_entity
   └─ Check error log?               → GET /api/error_log
```

### Phase 3: Execution & Validation

**Before Calling API:**
1. Do you have correct entity_id? (domain.name format)
2. Are you using the right HTTP method? (GET vs POST vs DELETE)
3. Is your authentication token valid?
4. For service calls, do you have the right parameters?

**During Execution:**
- Handle error responses appropriately (401, 404, 500, etc.)
- Retry on network errors with exponential backoff
- Monitor performance for polling operations

**After Execution:**
- Verify response matches expectation
- Check for error codes in response
- Cache results if applicable

## Common Task Patterns

### Query Current State

```bash
# Get one light's state
GET /api/states/light.kitchen

# Get temperature reading
GET /api/states/sensor.temperature

# Get all lights
GET /api/states
# Then filter: .[] | select(.entity_id | startswith("light."))
```

Load: `resources/state-management.md` then `resources/core-concepts.md` for HTTP details

### Turn on/off Devices

```bash
# Turn on light with brightness
POST /api/services/light/turn_on
{"entity_id": "light.kitchen", "brightness": 200}

# Turn off all lights
POST /api/services/light/turn_off
{"entity_id": "all"}

# Toggle switch
POST /api/services/switch/toggle
{"entity_id": "switch.coffee_maker"}
```

Load: `resources/service-reference.md` + `resources/entity-types.md` for specific parameters

### Query Multiple Entities

**Option 1: Multiple API calls** (simple, high bandwidth)
```bash
GET /api/states/light.kitchen
GET /api/states/light.living_room
GET /api/states/light.bedroom
```

**Option 2: Get all and filter** (one call, parse locally)
```bash
GET /api/states
# Filter in client: select by entity_id prefix
```

**Option 3: Server-side template** (most efficient)
```bash
POST /api/template
{"template": "{{ states.light | selectattr('state', 'eq', 'on') | list | length }}"}
```

Load: `resources/templates.md` for advanced queries

### Batch Operations

```bash
# Bad: Multiple sequential API calls
POST /api/services/light/turn_on {"entity_id": "light.kitchen"}
POST /api/services/light/turn_on {"entity_id": "light.living_room"}
POST /api/services/light/turn_on {"entity_id": "light.bedroom"}

# Better: Array of entities in one call
POST /api/services/light/turn_on
{"entity_id": ["light.kitchen", "light.living_room", "light.bedroom"]}

# Best: Use Home Assistant script (for complex multi-step)
POST /api/services/script/turn_on
{"entity_id": "script.my_scene"}
```

Load: `resources/examples.md` for working code patterns

## Entity Type Quick Reference

### Read-Only (Sensors)
- `sensor.*` - Numeric/text readings
- `binary_sensor.*` - On/off detection
- `camera.*` - Camera snapshots

Load: `resources/entity-types.md` for attributes

### Controllable Entities
- `light.*` - Lights (on/off, brightness, color)
- `switch.*` - Switches (on/off)
- `climate.*` - Thermostats (temperature, mode)
- `cover.*` - Blinds, doors (open/close, position)
- `lock.*` - Locks (lock/unlock)
- `fan.*` - Fans (on/off, speed, oscillate)
- `media_player.*` - Media devices (play/pause, volume)

Load: `resources/entity-types.md` then `resources/service-reference.md`

### Meta Entities (Non-device)
- `automation.*` - Automations (trigger, turn on/off)
- `script.*` - Scripts (turn on/off)
- `scene.*` - Scenes (activate)
- `group.*` - Entity groups
- `person.*` - Location tracking
- `device_tracker.*` - Device tracking
- `input_*` - Input helpers

### Status Entities
- `person.*` - "home" or "not_