Home Assistant

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

1. Open Home Assistant → Profile (bottom left) 2. Scroll to "Long-Lived Access Tokens" 3. Click "Create Token", name it (e.g., "Clawdbot") 4. 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

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_room

2. 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.

Home Assistant REST API Reference

Authentication

All requests require the Authorization header:

Authorization: Bearer <long-lived-access-token>

Base Endpoints

Common Services

Lights

# Turn on with options
POST /api/services/light/turn_on
{
  "entity_id": "light.living_room",
  "brightness": 255,           # 0-255
  "color_temp": 370,           # Mireds (153-500 typically)
  "rgb_color": [255, 0, 0],    # RGB array
  "transition": 2              # Seconds
}

# Turn off
POST /api/services/light/turn_off
{"entity_id": "light.living_room"}

Climate

# Set temperature
POST /api/services/climate/set_temperature
{
  "entity_id": "climate.thermostat",
  "temperature": 22,
  "hvac_mode": "heat"  # heat, cool, auto, off
}

# Set preset
POST /api/services/climate/set_preset_mode
{
  "entity_id": "climate.thermostat",
  "preset_mode": "away"
}

Media Player

# Play/pause
POST /api/services/media_player/media_play_pause
{"entity_id": "media_player.tv"}

# Set volume (0.0-1.0)
POST /api/services/media_player/volume_set
{"entity_id": "media_player.tv", "volume_level": 0.5}

# Play media
POST /api/services/media_player/play_media
{
  "entity_id": "media_player.tv",
  "media_content_type": "music",
  "media_content_id": "spotify:playlist:xyz"
}

Cover (Blinds/Garage)

POST /api/services/cover/open_cover
{"entity_id": "cover.garage"}

POST /api/services/cover/close_cover
{"entity_id": "cover.garage"}

POST /api/services/cover/set_cover_position
{"entity_id": "cover.blinds", "position": 50}  # 0=closed, 100=open

Notifications

POST /api/services/notify/mobile_app_phone
{
  "message": "Motion detected!",
  "title": "Security Alert",
  "data": {
    "image": "/local/camera_snapshot.jpg"
  }
}

Entity State Object

{
  "entity_id": "light.living_room",
  "state": "on",
  "attributes": {
    "brightness": 255,
    "color_temp": 370,
    "friendly_name": "Living Room Light",
    "supported_features": 63
  },
  "last_changed": "2024-01-15T10:30:00+00:00",
  "last_updated": "2024-01-15T10:30:00+00:00"
}

Webhooks (Inbound to HA)

Trigger automations via webhook:

POST /api/webhook/<webhook_id>
{"custom": "data"}

Create webhook trigger in automation:

automation:
  trigger:
    - platform: webhook
      webhook_id: my_webhook_id
      allowed_methods:
        - POST

WebSocket API

For real-time updates, use the WebSocket API at ws://ha-url/api/websocket.

Connection flow: 1. Connect to WebSocket 2. Receive auth_required 3. Send {"type": "auth", "access_token": "TOKEN"} 4. Receive auth_ok 5. Subscribe to events: {"id": 1, "type": "subscribe_events", "event_type": "state_changed"}

Error Responses

Rate Limits

Home Assistant doesn't enforce strict rate limits, but avoid:

• Polling faster than every 1 second
• Bulk updates without batching

Use WebSocket for real-time state tracking instead of polling.