home-assistant-api（home 助手 API）

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

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

# 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

# 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)

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)

GET /api/states
# Filter in client: select by entity_id prefix

Option 3: Server-side template (most efficient)

POST /api/template
{"template": "{{ states.light | selectattr('state', 'eq', 'on') | list | length }}"}

Load: resources/templates.md for advanced queries

Batch Operations

# 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_home"
• device_tracker.* - Location state
• sun.sun - "above_horizon" or "below_horizon"
• weather.* - Weather conditions

Service Call Parameters

Most Common Services

Load: resources/service-reference.md for complete reference

Response Handling

Success (200)

{
  "entity_id": "light.kitchen",
  "state": "on",
  "attributes": {...},
  "last_changed": "...",
  "last_updated": "...",
  "context": {...}
}

Authorization Error (401)

{
  "error": "Unauthorized",
  "message": "Invalid authentication provided"
}

Solution: Check token, regenerate if needed

Not Found (404)

{
  "error": "Entity not found",
  "message": "No entity found for domain 'light' and name 'nonexistent'"
}

Solution: Verify entity_id exists, check spelling

Bad Request (400)

{
  "error": "Invalid JSON",
  "message": "..."
}

Solution: Validate JSON syntax, required fields

Server Error (500)

Solution: Check HA error log, restart if needed

Load: resources/core-concepts.md for detailed error handling

Python Example Workflow

import requests

class HomeAssistant:
    def __init__(self, url, token):
        self.url = url
        self.headers = {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        }

    # State queries
    def get_state(self, entity_id):
        """Load: state-management.md"""
        return requests.get(f"{self.url}/api/states/{entity_id}",
                          headers=self.headers).json()

    # Service calls
    def turn_on_light(self, entity_id, brightness=None):
        """Load: service-reference.md + entity-types.md"""
        data = {"entity_id": entity_id}
        if brightness:
            data["brightness"] = brightness

        return requests.post(
            f"{self.url}/api/services/light/turn_on",
            headers=self.headers,
            json=data
        ).json()

    # Complex queries
    def count_on_lights(self):
        """Load: templates.md"""
        template = "{{ states.light | selectattr('state', 'eq', 'on') | list | length }}"
        resp = requests.post(
            f"{self.url}/api/template",
            headers=self.headers,
            json={"template": template}
        )
        return int(resp.json()['result'])

# Usage
ha = HomeAssistant("http://localhost:8123", "YOUR_TOKEN")

# Query state
kitchen = ha.get_state("light.kitchen")
print(f"Kitchen light: {kitchen['state']}")

# Control device
ha.turn_on_light("light.kitchen", brightness=200)

# Complex query
count = ha.count_on_lights()
print(f"{count} lights are on")

Load: resources/examples.md for complete working examples

Decision Matrix: Which Task?

Recommended Learning Path

New to Home Assistant API?

1. resources/core-concepts.md - Understand authentication and basics
2. resources/state-management.md - Learn to query state
3. resources/service-reference.md - Learn to control devices
4. resources/examples.md - See working code

Building an integration?

1. resources/core-concepts.md - Error handling, timeouts
2. resources/examples.md - Client setup, retry logic
3. resources/service-reference.md - Available operations
4. resources/templates.md - Complex queries

Power user optimizations?

1. resources/templates.md - Server-side queries
2. resources/system-config.md - Discovery, caching
3. resources/examples.md - Performance patterns

Next Step: Identify your task above, load the appropriate resource file, and proceed with implementation.