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:

curl -X GET \
  http://localhost:8123/api/states \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

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

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:

{
  "message": "API running."
}

Example:

curl http://localhost:8123/api/

GET /api/config

Get Home Assistant configuration.

Requires: Authentication, Admin

Response:

{
  "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:

[
  {
    "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:

curl -X GET \
  http://localhost:8123/api/states \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/states/

Get state of a specific entity.

Requires: Authentication

Response:

{
  "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:

curl -X GET \
  http://localhost:8123/api/states/light.living_room \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/states/

Update the state of an entity.

Requires: Authentication

Request Body:

{
  "state": "on",
  "attributes": {
    "brightness": 200
  }
}

Response: Returns the new state object.

Example:

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:

[
  {
    "event": "state_changed",
    "listener_count": 5
  },
  {
    "event": "homeassistant_start",
    "listener_count": 10
  }
]

POST /api/events/

Fire an event.

Requires: Authentication

Request Body:

{
  "event_data": {
    "key": "value"
  }
}

Response:

{
  "message": "Event event_type fired."
}

Example:

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:

[
  {
    "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//

Call a service.

Requires: Authentication

Request Body:

{
  "entity_id": "light.living_room",
  "brightness": 200
}

Response:

[
  {
    "entity_id": "light.living_room",
    "state": "on",
    "attributes": {
      "brightness": 200
    }
  }
]

Example:

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:

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": {...}}

The stream automatically pings every 50 seconds to keep the connection alive.

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:

{
  "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

Use Long-Lived Tokens

Create dedicated tokens for API access, not user passwords

Handle Errors

Check HTTP status codes and handle error responses

Respect Rate Limits

Don’t overwhelm the API with excessive requests

Use WebSocket for Real-Time

For real-time updates, use the WebSocket API instead of polling

See Also

WebSocket API

Real-time bidirectional communication API

Service Calls

Learn more about calling services

State Machine

Understand the state management system

Event System

Deep dive into the event bus