Home Assistant REST API Orchestration Skill 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:

Do you have correct entity_id? (domain.name format)
Are you using the right HTTP method? (GET vs POST vs DELETE)
Is your authentication token valid?
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?

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

Building an integration?

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

Power user optimizations?

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

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

Agent Skills: Home Assistant REST API Orchestration Skill

Install this agent skill to your local

Skill Files