home-assistant-api

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: home-assistant-api
description: Orchestrates access to the Home Assistant REST API for programmatic control of smart home devices. Routes requests to specialized resource files based on task type - authentication, state management, service calls, entity types, or advanced queries. Provides intelligent decision tables for selecting appropriate endpoints and managing integrations.
version: 2.0
---

# 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