Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us