> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> HTTP REST API for controlling and querying Home Assistant

The Home Assistant REST API allows you to interact with a Home Assistant instance using HTTP requests. The API is served over the HTTP component on the same port as the web interface (default: 8123).

## Overview

The REST API is implemented in the `api` component and provides endpoints for:

* Checking API status
* Reading and setting entity states
* Firing events
* Calling services
* Retrieving configuration information
* Streaming events

Source: `homeassistant/components/api/__init__.py`

## Authentication

All API requests (except for the status endpoint) require authentication. Include a long-lived access token in the `Authorization` header:

```bash theme={null}
curl -X GET \
  http://localhost:8123/api/states \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"
```

<Note>
  You can create long-lived access tokens in the Home Assistant UI under your user profile.
</Note>

## Base URL

All API endpoints are prefixed with `/api`. The base URL constants are defined in `homeassistant/const.py`:

* `URL_API` = "/api/"
* `URL_API_STATES` = "/api/states"
* `URL_API_EVENTS` = "/api/events"
* `URL_API_SERVICES` = "/api/services"

## Core Endpoints

### GET /api/

Check if the API is running.

**Response:**

```json theme={null}
{
  "message": "API running."
}
```

**Example:**

```bash theme={null}
curl http://localhost:8123/api/
```

### GET /api/config

Get Home Assistant configuration.

**Requires:** Authentication, Admin

**Response:**

```json theme={null}
{
  "location_name": "Home",
  "version": "2026.4.0",
  "uuid": "...",
  "base_url": "http://localhost:8123",
  "internal_url": "http://192.168.1.100:8123",
  "external_url": "https://example.com"
}
```

## State Endpoints

### GET /api/states

Get all entity states.

**Requires:** Authentication

**Response:**

```json theme={null}
[
  {
    "entity_id": "light.living_room",
    "state": "on",
    "attributes": {
      "brightness": 255,
      "friendly_name": "Living Room Light"
    },
    "last_changed": "2026-03-10T12:00:00.000000+00:00",
    "last_updated": "2026-03-10T12:00:00.000000+00:00"
  }
]
```

**Example:**

```bash theme={null}
curl -X GET \
  http://localhost:8123/api/states \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### GET /api/states/{entity_id}

Get state of a specific entity.

**Requires:** Authentication

**Response:**

```json theme={null}
{
  "entity_id": "light.living_room",
  "state": "on",
  "attributes": {
    "brightness": 255,
    "friendly_name": "Living Room Light"
  },
  "last_changed": "2026-03-10T12:00:00.000000+00:00",
  "last_updated": "2026-03-10T12:00:00.000000+00:00",
  "context": {
    "id": "...",
    "parent_id": null,
    "user_id": null
  }
}
```

**Example:**

```bash theme={null}
curl -X GET \
  http://localhost:8123/api/states/light.living_room \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### POST /api/states/{entity_id}

Update the state of an entity.

**Requires:** Authentication

**Request Body:**

```json theme={null}
{
  "state": "on",
  "attributes": {
    "brightness": 200
  }
}
```

**Response:** Returns the new state object.

**Example:**

```bash theme={null}
curl -X POST \
  http://localhost:8123/api/states/light.living_room \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "on",
    "attributes": {
      "brightness": 200
    }
  }'
```

## Event Endpoints

### GET /api/events

Get all event types that are being listened to.

**Requires:** Authentication

**Response:**

```json theme={null}
[
  {
    "event": "state_changed",
    "listener_count": 5
  },
  {
    "event": "homeassistant_start",
    "listener_count": 10
  }
]
```

### POST /api/events/{event_type}

Fire an event.

**Requires:** Authentication

**Request Body:**

```json theme={null}
{
  "event_data": {
    "key": "value"
  }
}
```

**Response:**

```json theme={null}
{
  "message": "Event event_type fired."
}
```

**Example:**

```bash theme={null}
curl -X POST \
  http://localhost:8123/api/events/my_custom_event \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_data": {"message": "Hello"}}'
```

## Service Endpoints

### GET /api/services

Get all available services.

**Requires:** Authentication

**Response:**

```json theme={null}
[
  {
    "domain": "light",
    "services": {
      "turn_on": {
        "description": "Turn on one or more lights",
        "fields": {
          "entity_id": {
            "description": "Entity ID",
            "example": "light.living_room"
          },
          "brightness": {
            "description": "Brightness value 0-255",
            "example": 200
          }
        }
      }
    }
  }
]
```

### POST /api/services/{domain}/{service}

Call a service.

**Requires:** Authentication

**Request Body:**

```json theme={null}
{
  "entity_id": "light.living_room",
  "brightness": 200
}
```

**Response:**

```json theme={null}
[
  {
    "entity_id": "light.living_room",
    "state": "on",
    "attributes": {
      "brightness": 200
    }
  }
]
```

**Example:**

```bash theme={null}
curl -X POST \
  http://localhost:8123/api/services/light/turn_on \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "light.living_room",
    "brightness": 200
  }'
```

## Event Stream

### GET /api/stream

Open a streaming connection for server-sent events.

**Requires:** Authentication, Admin

**Query Parameters:**

* `restrict` (optional): Comma-separated list of event types to receive

**Example:**

```bash theme={null}
curl -X GET \
  "http://localhost:8123/api/stream?restrict=state_changed" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: text/event-stream"
```

The stream sends periodic ping messages and event data:

```
event: message
data: ping

event: message
data: {"event_type": "state_changed", "data": {...}}
```

<Note>
  The stream automatically pings every 50 seconds to keep the connection alive.
</Note>

## Error Responses

The API returns standard HTTP status codes:

* `200 OK`: Request succeeded
* `400 Bad Request`: Invalid request format
* `401 Unauthorized`: Missing or invalid authentication token
* `403 Forbidden`: Insufficient permissions
* `404 Not Found`: Entity or endpoint not found
* `500 Internal Server Error`: Server error

**Error Response Format:**

```json theme={null}
{
  "message": "Error message describing what went wrong"
}
```

## Implementation Details

The REST API is implemented using `aiohttp` views. Key views from `homeassistant/components/api/__init__.py`:

* `APIStatusView` - API status check
* `APICoreStateView` - Core state retrieval
* `APIStatesView` - All states
* `APIEntityStateView` - Single entity state
* `APIEventListenersView` - Event listeners
* `APIEventView` - Fire events
* `APIServicesView` - List all services
* `APIDomainServicesView` - Services for a domain
* `APIEventStream` - Server-sent event stream

Each view extends `HomeAssistantView` and implements HTTP method handlers.

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Long-Lived Tokens" icon="key">
    Create dedicated tokens for API access, not user passwords
  </Card>

  <Card title="Handle Errors" icon="triangle-exclamation">
    Check HTTP status codes and handle error responses
  </Card>

  <Card title="Respect Rate Limits" icon="gauge">
    Don't overwhelm the API with excessive requests
  </Card>

  <Card title="Use WebSocket for Real-Time" icon="bolt">
    For real-time updates, use the WebSocket API instead of polling
  </Card>
</CardGroup>

## See Also

<CardGroup cols={2}>
  <Card title="WebSocket API" icon="plug" href="/api/websocket-api">
    Real-time bidirectional communication API
  </Card>

  <Card title="Service Calls" icon="phone" href="/architecture/service-calls">
    Learn more about calling services
  </Card>

  <Card title="State Machine" icon="database" href="/architecture/state-machine">
    Understand the state management system
  </Card>

  <Card title="Event System" icon="bell" href="/architecture/event-system">
    Deep dive into the event bus
  </Card>
</CardGroup>