claude-skills/skills/homeassistant/references/api_reference.md

Home Assistant API Reference

REST API

Authentication

All API requests require a Long-Lived Access Token passed in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Obtain tokens from: http://YOUR_HA_URL:8123/profile

Base URL

http://YOUR_HA_URL:8123/api/

Key Endpoints

Get All Entity States

GET /api/states

Returns array of all entities with their current states, attributes, and timestamps.

Get Specific Entity State

GET /api/states/<entity_id>

Example: /api/states/light.living_room

Returns single entity object with state, attributes, last_changed, last_updated.

Call a Service

POST /api/services/<domain>/<service>

Example: /api/services/light/turn_on

Request body (optional):

{
  "entity_id": "light.living_room",
  "brightness": 255,
  "color_name": "blue"
}

Returns array of entity states that were changed by the service call.

List All Services

GET /api/services

Returns object with domains as keys, each containing available services with descriptions and field definitions.

Get Configuration

GET /api/config

Returns Home Assistant configuration including version, location, unit system, time zone, etc.

Get Error Log

GET /api/error_log

Returns text content of the error log.

Response Codes

• 200 - Success (existing resource)
• 201 - Created (new resource)
• 400 - Bad Request
• 401 - Unauthorized
• 404 - Not Found
• 405 - Method Not Allowed

WebSocket API

Connection

Connect to: ws://YOUR_HA_URL:8123/api/websocket

Authentication Flow

1. Client connects
2. Server sends auth_required message:

{
  "type": "auth_required",
  "ha_version": "2024.1.0"
}

3. Client sends auth message:

{
  "type": "auth",
  "access_token": "YOUR_TOKEN_HERE"
}

4. Server responds with either:

{"type": "auth_ok"}

or

{
  "type": "auth_invalid",
  "message": "Invalid access token"
}

Message Format

All messages use JSON. Command phase messages require an id field for request/response correlation.

Common Commands

Get All States

{
  "id": 1,
  "type": "get_states"
}

Response:

{
  "id": 1,
  "type": "result",
  "success": true,
  "result": [
    {
      "entity_id": "light.living_room",
      "state": "on",
      "attributes": {...},
      "last_changed": "2024-01-15T10:30:00+00:00",
      "last_updated": "2024-01-15T10:30:00+00:00"
    }
  ]
}

Call Service

{
  "id": 2,
  "type": "call_service",
  "domain": "light",
  "service": "turn_on",
  "target": {
    "entity_id": "light.kitchen"
  },
  "service_data": {
    "brightness": 255,
    "color_name": "warm_white"
  },
  "return_response": true
}

Response:

{
  "id": 2,
  "type": "result",
  "success": true,
  "result": {
    "context": {
      "id": "326ef27d19415c60c492fe330945f954",
      "parent_id": null,
      "user_id": "31ddb597e03147118cf8d2f8fbea5553"
    },
    "response": null
  }
}

Subscribe to Events

Subscribe to state changes:

{
  "id": 3,
  "type": "subscribe_events",
  "event_type": "state_changed"
}

Server confirms subscription:

{
  "id": 3,
  "type": "result",
  "success": true
}

Then sends events as they occur:

{
  "id": 3,
  "type": "event",
  "event": {
    "event_type": "state_changed",
    "data": {
      "entity_id": "sensor.temperature",
      "old_state": {...},
      "new_state": {...}
    }
  }
}

Unsubscribe from Events

{
  "id": 4,
  "type": "unsubscribe_events",
  "subscription": 3
}

Error Responses

{
  "id": 5,
  "type": "result",
  "success": false,
  "error": {
    "code": "invalid_format",
    "message": "Message incorrectly formatted"
  }
}

Common Entity Domains

• light - Lights
• switch - Switches
• sensor - Sensors (read-only)
• binary_sensor - Binary sensors (on/off, open/closed)
• climate - Climate control (thermostats, AC)
• cover - Covers (blinds, garage doors)
• fan - Fans
• media_player - Media players
• camera - Cameras
• lock - Door locks
• alarm_control_panel - Alarm systems
• vacuum - Vacuum cleaners
• automation - Automations themselves
• script - Scripts
• scene - Scenes

Common Service Patterns

Most domains support these services:

• turn_on - Turn entity on
• turn_off - Turn entity off
• toggle - Toggle entity state

Domain-specific services may include additional parameters like brightness, color_temp, position, etc.