SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillshome-assistant-api

home-assistant-api

Coding & development

View repository

Updated 10-16 00:06

About this skill

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

# 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

Domain Service Key Parameters
light turn_on entity_id, brightness, rgb_color, transition
light turn_off entity_id, transition
switch turn_on entity_id
switch turn_off entity_id
climate set_temperature entity_id, temperature, hvac_mode
climate set_hvac_mode entity_id, hvac_mode
cover open_cover entity_id
cover set_cover_position entity_id, position (0-100)
lock lock entity_id, code (optional)
lock unlock entity_id, code (optional)
fan turn_on entity_id, percentage, preset_mode
media_player play_media entity_id, media_content_id, media_content_type
notify mobile_app_* message, title, data
automation trigger entity_id
script turn_on entity_id
scene turn_on entity_id, transition

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?

I want to... Load Resource Example
Understand how to authenticate core-concepts.md Getting access token
Query temperature or sensor value state-management.md GET /api/states/sensor.temp
Turn on a light service-reference.md → entity-types.md POST /api/services/light/turn_on
Find devices with low battery templates.md Server-side template query
Understand light color options entity-types.md Brightness, RGB, HS color
Count how many lights are on templates.md selectattr filter
Check if config is valid system-config.md POST /api/config/core/check_config
Write working Python code examples.md Complete client implementation
Handle errors properly core-concepts.md → examples.md Retry logic, error codes
Batch control multiple devices service-reference.md → examples.md Array of entity_ids

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.