Home Assistant
Control your smart home via Home Assistant's REST API and webhooks.
Setup
Option 1: Config File (Recommended)
Create ~/.config/home-assistant/config.json:
{
"url": "https://your-ha-instance.duckdns.org",
"token": "your-long-lived-access-token"
}Option 2: Environment Variables
export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your-long-lived-access-token"Getting a Long-Lived Access Token
- Open Home Assistant → Profile (bottom left)
- Scroll to "Long-Lived Access Tokens"
- Click "Create Token", name it (e.g., "Clawdbot")
- Copy the token immediately (shown only once)
Quick Reference
List Entities
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '.[].entity_id'Get Entity State
curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/light.living_room"Control Devices
# Turn on
curl -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"}'
# Turn off
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
"$HA_URL/api/services/light/turn_off" -d '{"entity_id": "light.living_room"}'
# Set brightness (0-255)
curl -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}'Run Scripts & Automations
# Trigger script
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/script/turn_on" \
-H "Content-Type: application/json" -d '{"entity_id": "script.goodnight"}'
# Trigger automation
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/automation/trigger" \
-H "Content-Type: application/json" -d '{"entity_id": "automation.motion_lights"}'Activate Scenes
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/scene/turn_on" \
-H "Content-Type: application/json" -d '{"entity_id": "scene.movie_night"}'Common Services
| Domain | Service | Example entity_id |
|---|---|---|
light | turn_on, turn_off, toggle | light.kitchen |
switch | turn_on, turn_off, toggle | switch.fan |
climate | set_temperature, set_hvac_mode | climate.thermostat |
cover | open_cover, close_cover, stop_cover | cover.garage |
media_player | play_media, media_pause, volume_set | media_player.tv |
scene | turn_on | scene.relax |
script | turn_on | script.welcome_home |
automation | trigger, turn_on, turn_off | automation.sunrise |
Inbound Webhooks (HA → Clawdbot)
To receive events from Home Assistant automations:
1. Create HA Automation with Webhook Action
# In HA automation
action:
- service: rest_command.notify_clawdbot
data:
event: motion_detected
area: living_room2. Define REST Command in HA
# configuration.yaml
rest_command:
notify_clawdbot:
url: "https://your-clawdbot-url/webhook/home-assistant"
method: POST
headers:
Authorization: "Bearer {{ webhook_secret }}"
Content-Type: "application/json"
payload: '{"event": "{{ event }}", "area": "{{ area }}"}'3. Handle in Clawdbot
Clawdbot receives the webhook and can notify you or take action based on the event.
CLI Wrapper
The scripts/ha.sh CLI provides easy access to all HA functions:
# Test connection
ha.sh info
# List entities
ha.sh list all # all entities
ha.sh list lights # just lights
ha.sh list switch # just switches
# Search entities
ha.sh search kitchen # find entities by name
# Get/set state
ha.sh state light.living_room
ha.sh states light.living_room # full details with attributes
ha.sh on light.living_room
ha.sh on light.living_room 200 # with brightness (0-255)
ha.sh off light.living_room
ha.sh toggle switch.fan
# Scenes & scripts
ha.sh scene movie_night
ha.sh script goodnight
# Climate
ha.sh climate climate.thermostat 22
# Call any service
ha.sh call light turn_on '{"entity_id":"light.room","brightness":200}'Troubleshooting
- 401 Unauthorized: Token expired or invalid. Generate a new one.
- Connection refused: Check HA_URL, ensure HA is running and accessible.
- Entity not found: List entities to find the correct entity_id.
API Reference
For advanced usage, see references/api.md.