home-assistant

name	home-assistant
description	Control your smart home devices through your agent. Lights, thermostats, locks, cameras, scenes — all via the Home Assistant API.

Home Assistant

Control your smart home devices through your agent. Lights, thermostats, locks, cameras, scenes — all via the Home Assistant API.

Category: home, automation API Key Required: Yes (Home Assistant Long-Lived Access Token)

What It Does

Connects your agent to Home Assistant so you can control your entire smart home through conversation. "Turn off the living room lights," "Set the thermostat to 21," "Lock the front door," "What's the temperature in the bedroom?" — all handled.

Setup

Step 1: Get your Home Assistant details

You need:

1. Home Assistant URL — usually http://YOUR_IP:8123 or your Nabu Casa URL
2. Long-Lived Access Token — create one at: Profile (bottom left) > Long-Lived Access Tokens > Create Token

Store these in your agent's config:

HA_URL=http://192.168.1.XXX:8123
HA_TOKEN=your_long_lived_access_token

Step 2: Test the connection

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/" | python3 -m json.tool

Should return {"message": "API running."}.

Agent Commands

List all entities

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | python3 -c "
import json,sys
states = json.load(sys.stdin)
for s in sorted(states, key=lambda x: x['entity_id']):
    print(f\"{s['entity_id']:50s} {s['state']:15s} {s['attributes'].get('friendly_name','')}\")
" | head -50

Get entity state

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/ENTITY_ID" | python3 -m json.tool

Turn on/off a device

# Turn on
curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/homeassistant/turn_on" \
  -d '{"entity_id": "light.living_room"}'

# Turn off
curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/homeassistant/turn_off" \
  -d '{"entity_id": "light.living_room"}'

Set light brightness/color

curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/light/turn_on" \
  -d '{"entity_id": "light.living_room", "brightness": 128, "color_name": "warm_white"}'

Set thermostat temperature

curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/climate/set_temperature" \
  -d '{"entity_id": "climate.thermostat", "temperature": 21}'

Lock/unlock

# Lock
curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/lock/lock" \
  -d '{"entity_id": "lock.front_door"}'

# Unlock
curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/lock/unlock" \
  -d '{"entity_id": "lock.front_door"}'

Activate a scene

curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/scene/turn_on" \
  -d '{"entity_id": "scene.movie_night"}'

Get sensor readings (temperature, humidity, etc.)

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/sensor.bedroom_temperature" | python3 -c "
import json,sys
s = json.load(sys.stdin)
print(f\"{s['attributes'].get('friendly_name','')}: {s['state']} {s['attributes'].get('unit_of_measurement','')}\")
"

Get history for an entity

# Last 24 hours
curl -s -H "Authorization: Bearer $HA_TOKEN" \
  "$HA_URL/api/history/period?filter_entity_id=sensor.bedroom_temperature&minimal_response" | python3 -m json.tool

Run an automation

curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/automation/trigger" \
  -d '{"entity_id": "automation.morning_routine"}'

Check who's home

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | python3 -c "
import json,sys
states = json.load(sys.stdin)
for s in states:
    if s['entity_id'].startswith('person.'):
        print(f\"{s['attributes'].get('friendly_name','')}: {s['state']}\")
"

Common Entity Types

• light.* — lights (on/off, brightness, color)
• switch.* — smart plugs, switches
• climate.* — thermostats, AC
• lock.* — smart locks
• cover.* — blinds, garage doors
• sensor.* — temperature, humidity, power usage
• binary_sensor.* — motion, doors, windows (on/off)
• media_player.* — Sonos, Chromecast, TVs
• camera.* — security cameras
• scene.* — predefined device states
• automation.* — automations
• person.* — presence tracking

Examples

User: "Turn off all the lights" → List all light.* entities, call homeassistant/turn_off for each

User: "What's the temperature downstairs?" → Find sensor.*temperature* entities with "downstairs" in the name, report state

User: "Set movie mode" → Look for a scene called "movie" and activate it

User: "Is the front door locked?" → Check lock.front_door state

Constraints

• Requires Home Assistant instance running and accessible from this machine
• Long-lived tokens don't expire but can be revoked in HA
• Some devices may have rate limits (e.g. cloud-connected devices)
• Camera snapshots require different API endpoint and may be large