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

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.