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

```http
GET /api/states
```

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

#### Get Specific Entity State

```http
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

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

Example: `/api/services/light/turn_on`

Request body (optional):
```json
{
  "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

```http
GET /api/services
```

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

#### Get Configuration

```http
GET /api/config
```

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

#### Get Error Log

```http
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:
```json
{
  "type": "auth_required",
  "ha_version": "2024.1.0"
}
```

3. Client sends `auth` message:
```json
{
  "type": "auth",
  "access_token": "YOUR_TOKEN_HERE"
}
```

4. Server responds with either:
```json
{"type": "auth_ok"}
```
or
```json
{
  "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

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

Response:
```json
{
  "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

```json
{
  "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:
```json
{
  "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:
```json
{
  "id": 3,
  "type": "subscribe_events",
  "event_type": "state_changed"
}
```

Server confirms subscription:
```json
{
  "id": 3,
  "type": "result",
  "success": true
}
```

Then sends events as they occur:
```json
{
  "id": 3,
  "type": "event",
  "event": {
    "event_type": "state_changed",
    "data": {
      "entity_id": "sensor.temperature",
      "old_state": {...},
      "new_state": {...}
    }
  }
}
```

#### Unsubscribe from Events

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

### Error Responses

```json
{
  "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.