Home Assistant REST API

https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md
Admin
Home Assistant provides a RESTful API for controlling and monitoring home automation devices,...
Tokens:14,589
Snippets:94
Trust Score:7.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Turn Light On Example (RESTful Command)

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

This example shows how to use the RESTful Command integration in Home Assistant to turn on a light, demonstrating a POST request with a JSON payload.

```APIDOC
## Turn Light On Example (RESTful Command)

### Description
This example shows how to use the RESTful Command integration in Home Assistant to turn on a light, demonstrating a POST request with a JSON payload.

### Method
POST

### Endpoint
`http://localhost:8123/api/states/light.study_light`

### Headers
- `authorization`: `Bearer TOKEN`
- `content-type`: `application/json`

### Request Body
- `state` (string) - Required - The desired state, e.g., "on"

### Request Example
```yaml
turn_light_on:
  url: http://localhost:8123/api/states/light.study_light
  method: POST
  headers:
    authorization: 'Bearer TOKEN'
    content-type: 'application/json'
  payload: '{"state":"on"}'
```
```

--------------------------------

### General API Call Example

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

This example demonstrates how to make a general API call using curl, including the required Authorization and Content-Type headers.

```APIDOC
## General API Call Example

### Description
This example demonstrates how to make a general API call using curl, including the required Authorization and Content-Type headers.

### Method
GET (or other applicable HTTP methods)

### Endpoint
`http://IP_ADDRESS:8123/ENDPOINT`

### Headers
- `Authorization`: `Bearer TOKEN` (Required)
- `Content-Type`: `application/json` (Required for POST/PUT/PATCH)

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  http://IP_ADDRESS:8123/ENDPOINT
```
```

--------------------------------

### Get Minimal History with Manual Start Date

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Fetches a minimal history response for multiple entity IDs, starting from a manually specified date and time. The `minimal_response` flag reduces the amount of data returned. Replace 'TOKEN' with your actual Home Assistant API token.

```shell
# Minimal history of the entity 'sensor.temperature' and 'sensor.kitchen_temperature' of the past day where the beginning date is set manually to 2023-09-04
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/history/period/2023-09-04T00:00:00+02:00?filter_entity_id=sensor.temperature,sensor.kitchen_temperature&minimal_response"
```

--------------------------------

### Get Configuration

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves the current Home Assistant configuration as a JSON object.

```APIDOC
## GET /api/config

### Description
Returns the current configuration as JSON.

### Method
GET

### Endpoint
/api/config

### Response
#### Success Response (200)
- **components** (array) - List of loaded components.
- **config_dir** (string) - Path to the configuration directory.
- **elevation** (number) - Elevation of the location.
- **latitude** (number) - Latitude of the location.
- **location_name** (string) - Name of the location.
- **longitude** (number) - Longitude of the location.
- **time_zone** (string) - Time zone of the location.
- **unit_system** (object) - Unit system configuration (length, mass, temperature, volume).
- **version** (string) - Home Assistant version.
- **whitelist_external_dirs** (array) - List of whitelisted external directories.

### Response Example
```json
{
   "components":[
      "sensor.cpuspeed",
      "frontend",
      "config.core",
      "http",
      "map",
      "api",
      "sun",
      "config",
      "discovery",
      "conversation",
      "recorder",
      "group",
      "sensor",
      "websocket_api",
      "automation",
      "config.automation",
      "config.customize"
   ],
   "config_dir":"/home/ha/.homeassistant",
   "elevation":510,
   "latitude":45.8781529,
   "location_name":"Home",
   "longitude":8.458853651,
   "time_zone":"Europe/Zurich",
   "unit_system":{
      "length":"km",
      "mass":"g",
      "temperature":"\u00b0C",
      "volume":"L"
   },
   "version":"0.56.2",
   "whitelist_external_dirs":[
      "/home/ha/.homeassistant/www",
      "/home/ha/.homeassistant/"
   ]
}
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/config
```
```

--------------------------------

### Get Components

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves a list of all currently loaded components in Home Assistant.

```APIDOC
## GET /api/components

### Description
Returns a list of currently loaded components.

### Method
GET

### Endpoint
/api/components

### Response
#### Success Response (200)
- (array) - List of component names.

### Response Example
```
[
  "currentcost.sensor",
  "tapo.switch",
  "tuya_ble.sensor",
  "backup",
  "ble_monitor.binary_sensor",
  "localtuya.remote",
  "logger",
  "http",
  "hacs",
  "cast",
  "device_tracker",
  "upnp.binary_sensor",
  "notify",
  "person",
  ...
]
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/components
```
```

--------------------------------

### Get History with Manual Start Date and Minimal Response

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves history for specified entity IDs starting from a manual date and time, with a minimal response format. Requires authentication.

```APIDOC
## GET /api/history/period/{start_date}

### Description
Retrieves history for specified entity IDs starting from a manual date and time, with a minimal response format.

### Method
GET

### Endpoint
/api/history/period/{start_date}

### Parameters
#### Path Parameters
- **start_date** (string) - Required - The start date and time for the history period (e.g., `2023-09-04T00:00:00+02:00`).

#### Query Parameters
- **filter_entity_id** (string) - Required - Comma-separated list of entity IDs to filter history for (e.g., `sensor.temperature,sensor.kitchen_temperature`).
- **minimal_response** (boolean) - Optional - If set, returns a minimal response.

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/history/period/2023-09-04T00:00:00+02:00?filter_entity_id=sensor.temperature,sensor.kitchen_temperature&minimal_response"
```
```

--------------------------------

### Sample curl command for API Components

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Example `curl` command to list all loaded components in Home Assistant. Use your API token for authentication.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/components
```

--------------------------------

### Render a Home Assistant template using curl

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

This `curl` command shows how to send a template to the API for rendering. The `now()` function is used as an example.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "It is {{ now() }}!"}' http://localhost:8123/api/template
```

--------------------------------

### Get Historical State Changes (Full Response)

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves historical state changes for entities over a specified period. This example shows the full response format without optimizations.

```json
[
    [
        {
            "attributes": {
                "friendly_name": "Weather Temperature",
                "unit_of_measurement": "\u00b0C"
            },
            "entity_id": "sensor.weather_temperature",
            "last_changed": "2016-02-06T22:15:00+00:00",
            "last_updated": "2016-02-06T22:15:00+00:00",
            "state": "-3.9"
        },
        {
            "attributes": {
                "friendly_name": "Weather Temperature",
                "unit_of_measurement": "\u00b0C"
            },
            "entity_id": "sensor.weather_temperature",
            "last_changed": "2016-02-06T22:15:00+00:00",
            "last_updated": "2016-02-06T22:15:00+00:00",
            "state": "-1.9"
        },
    ]
]
```

--------------------------------

### Sample curl command for API Configuration

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Example `curl` command to retrieve the Home Assistant configuration. Ensure you replace `TOKEN` with your valid API token.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/config
```

--------------------------------

### Get Services

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves a list of available services, grouped by domain.

```APIDOC
## GET /api/services

### Description
Returns an array of service objects. Each object contains the domain and which services it contains.

### Method
GET

### Endpoint
/api/services

### Response
#### Success Response (200)
- **domain** (string) - The domain of the services.
- **services** (array) - A list of service names within the domain.

### Response Example
```json
[
    {
      "domain": "browser",
      "services": [
        "browse_url"
      ]
    },
    {
      "domain": "keyboard",
      "services": [
        "volume_up",
        "volume_down"
      ]
    }
]
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/services
```
```

--------------------------------

### Sample curl command for API Events

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Example `curl` command to fetch the list of events and their listener counts. Authenticate with your API token.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/events
```

--------------------------------

### Sample curl command for API Services

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Example `curl` command to retrieve available services, grouped by domain. Ensure your API token is included.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/services
```

--------------------------------

### Get API Services

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Returns an array of service objects, organized by domain, listing the services available within each domain.

```json
[
    {
      "domain": "browser",
      "services": [
        "browse_url"
      ]
    },
    {
      "domain": "keyboard",
      "services": [
        "volume_up",
        "volume_down"
      ]
    }
]
```

--------------------------------

### Get Calendars

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Returns a list of all configured calendar entities in Home Assistant.

```APIDOC
## GET /api/calendars

### Description
Returns the list of calendar entities.

### Method
GET

### Endpoint
/api/calendars

### Response
#### Success Response (200)
- **entity_id** (string) - The unique identifier for the calendar entity.
- **name** (string) - The display name of the calendar.

### Response Example
```json
[
  {
    "entity_id": "calendar.holidays",
    "name": "National Holidays",
  },
  {
    "entity_id": "calendar.personal",
    "name": "Personal Calendar",
  }
]
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8123/api/calendars
```
```

--------------------------------

### Get Home Assistant Configuration

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves the current Home Assistant configuration, including components, directories, location details, and version information.

```json
{
   "components":[
      "sensor.cpuspeed",
      "frontend",
      "config.core",
      "http",
      "map",
      "api",
      "sun",
      "config",
      "discovery",
      "conversation",
      "recorder",
      "group",
      "sensor",
      "websocket_api",
      "automation",
      "config.automation",
      "config.customize"
   ],
   "config_dir":"/home/ha/.homeassistant",
   "elevation":510,
   "latitude":45.8781529,
   "location_name":"Home",
   "longitude":8.458853651,
   "time_zone":"Europe/Zurich",
   "unit_system":{
      "length":"km",
      "mass":"g",
      "temperature":"\u00b0C",
      "volume":"L"
   },
   "version":"0.56.2",
   "whitelist_external_dirs":[
      "/home/ha/.homeassistant/www",
      "/home/ha/.homeassistant/"
   ]
}
```

--------------------------------

### Sample curl command for API Status

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Example `curl` command to check the status of the Home Assistant API. Replace `TOKEN` with your actual API token.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/
```

--------------------------------

### Get Calendar Events

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieve a list of calendar events for a specified entity ID within a given time range. The response includes event summaries, start and end times, and optional descriptions and locations.

```json
[
  {
    "summary": "Cinco de Mayo",
    "start": {
      "date": "2022-05-05"
    },
    "end": {
      "date": "2022-05-06"
    }
  },
  {
    "summary": "Birthday Party",
    "start": {
      "dateTime": "2022-05-06T20:00:00-07:00"
    },
    "end": {
      "dateTime": "2022-05-06T23:00:00-07:00"
    },
    "description": "Don't forget to bring balloons",
    "location": "Brian's House"
  }
]
```

--------------------------------

### Get History Between Two Dates

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves the history for a specified entity ID within a defined period between a start and end date. Requires authentication.

```APIDOC
## GET /api/history/period/{start_date}/{end_date}

### Description
Retrieves the history for a specified entity ID within a defined period between a start and end date.

### Method
GET

### Endpoint
/api/history/period/{start_date}/{end_date}

### Parameters
#### Path Parameters
- **start_date** (string) - Required - The start date for the history period (e.g., `2021-09-04`).
- **end_date** (string) - Required - The end date for the history period (e.g., `2023-09-04`).

#### Query Parameters
- **filter_entity_id** (string) - Required - The entity ID to filter history for (e.g., `sensor.temperature`).

### Request Example
```shell
# History of the entity 'sensor.temperature' during the period from 2021-09-04 to 2023-09-04
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/history/period/2021-09-04/2023-09-04?filter_entity_id=sensor.temperature"
```
```

--------------------------------

### Get API Status

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Returns a message indicating if the API is running.

```APIDOC
## GET /api/

### Description
Returns a message if the API is up and running.

### Method
GET

### Endpoint
/api/

### Response
#### Success Response (200)
- **message** (string) - Indicates the API is running.

### Response Example
```json
{
  "message": "API running."
}
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/
```

Note: make sure you include the trailing `/`, the full path is `/api/`, NOT `/api`
```

--------------------------------

### Get History Between Two Dates

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves the history for a specified entity ID within a defined date range. The start and end dates are inclusive.

```shell
# History of the entity 'sensor.temperature' during the period from 2021-09-04 to 2023-09-04
```

--------------------------------

### Get Events

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves a list of all active events and their listener counts.

```APIDOC
## GET /api/events

### Description
Returns an array of event objects. Each event object contains event name and listener count.

### Method
GET

### Endpoint
/api/events

### Response
#### Success Response (200)
- **event** (string) - The name of the event.
- **listener_count** (number) - The number of listeners for the event.

### Response Example
```json
[
    {
      "event": "state_changed",
      "listener_count": 5
    },
    {
      "event": "time_changed",
      "listener_count": 2
    }
]
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/events
```
```

--------------------------------

### Get Calendar Events

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves a list of calendar events for a specified calendar entity ID between a start and end time. The times are exclusive. Events can be all-day events or have specific date-times.

```APIDOC
## GET /api/calendars/<calendar entity_id>?start=<timestamp>&end=<timestamp>

### Description
Returns the list of [calendar events](/docs/core/entity/calendar/#calendarevent) for the specified calendar `entity_id` between the `start` and `end` times (exclusive).

The events in the response have a `start` and `end` that contain either `dateTime` or `date` for an all day event.

### Parameters
#### Query Parameters
- **start** (timestamp) - Required - The start timestamp for the event search.
- **end** (timestamp) - Required - The end timestamp for the event search.

#### Path Parameters
- **calendar entity_id** (string) - Required - The entity ID of the calendar.

### Response
#### Success Response (200)
- **summary** (string) - The summary of the event.
- **start** (object) - The start time of the event, can contain `date` or `dateTime`.
- **end** (object) - The end time of the event, can contain `date` or `dateTime`.
- **description** (string) - Optional description of the event.
- **location** (string) - Optional location of the event.

### Response Example
```json
[
  {
    "summary": "Cinco de Mayo",
    "start": {
      "date": "2022-05-05"
    },
    "end": {
      "date": "2022-05-06"
    }
  },
  {
    "summary": "Birthday Party",
    "start": {
      "dateTime": "2022-05-06T20:00:00-07:00"
    },
    "end": {
      "dateTime": "2022-05-06T23:00:00-07:00"
    },
    "description": "Don't forget to bring balloons",
    "location": "Brian's House"
  }
]
```
```

--------------------------------

### Get Error Log

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves all errors logged during the current session of Home Assistant as a plaintext response.

```APIDOC
## GET /api/error_log

### Description
Retrieve all errors logged during the current session of Home Assistant as a plaintext response.

### Method
GET

### Endpoint
/api/error_log

### Response
#### Success Response (200)
- The response is a plaintext string containing error messages.

### Response Example
```text
15-12-20 11:02:50 homeassistant.components.recorder: Found unfinished sessions
15-12-20 11:03:03 netdisco.ssdp: Error fetching description at http://192.168.1.1:8200/rootDesc.xml
15-12-20 11:04:36 homeassistant.components.alexa: Received unknown intent HelpIntent
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8123/api/error_log
```
```

--------------------------------

### Get API Events

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves an array of event objects, each detailing an event name and its current listener count.

```json
[
    {
      "event": "state_changed",
      "listener_count": 5
    },
    {
      "event": "time_changed",
      "listener_count": 2
    }
]
```

--------------------------------

### Call Calendar Events API with Curl

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Example of how to call the calendar events API using curl, including authorization and content type headers.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/calendars/calendar.holidays?start=2022-05-01T07:00:00.000Z&end=2022-06-12T07:00:00.000Z"
```

--------------------------------

### Get Logbook Entries

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Returns an array of logbook entries. The timestamp in the URL is optional and defaults to 1 day before the request time.

```APIDOC
## GET /api/logbook/<timestamp>

### Description
Returns an array of logbook entries. The timestamp in the URL is optional and defaults to 1 day before the request time. It determines the beginning of the period.

### Method
GET

### Endpoint
/api/logbook/<timestamp>

### Parameters
#### Query Parameters
- **entity** (string) - Optional - Filters the logbook entries for a specific entity ID.
- **end_time** (string) - Optional - The end time for the logbook entries, in URL encoded format.

### Response
#### Success Response (200)
- **context_user_id** (any) - Description not available.
- **domain** (string) - The domain of the logbook entry.
- **entity_id** (string) - The entity ID associated with the logbook entry.
- **message** (string) - The log message.
- **name** (string) - The name of the entity.
- **when** (string) - The timestamp when the event occurred.

### Response Example
```json
[
  {
		"context_user_id": null,
		"domain": "alarm_control_panel",
		"entity_id": "alarm_control_panel.area_001",
		"message": "changed to disarmed",
		"name": "Security",
		"when": "2020-06-20T16:44:26.127295+00:00"
	},
	{
		"context_user_id": null,
		"domain": "homekit",
		"entity_id": "alarm_control_panel.area_001",
		"message": "send command alarm_arm_night for Security",
		"name": "HomeKit",
		"when": "2020-06-21T02:59:05.759645+00:00"
	},
	{
		"context_user_id": null,
		"domain": "alarm_control_panel",
		"entity_id": "alarm_control_panel.area_001",
		"message": "changed to armed_night",
		"name": "Security",
		"when": "2020-06-21T02:59:06.015463+00:00"
	}
]
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00
```

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00?end_time=2099-12-31T00%3A00%3A00%2B02%3A00&entity=sensor.temperature"
```

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00?end_time=2099-12-31T00%3A00%3A00%2B02%3A00"
```
```

--------------------------------

### Make a REST API Call with Python Requests

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Utilize the Python Requests module to interact with the Home Assistant API. This example demonstrates fetching data from an endpoint.

```python
from requests import get

url = "http://localhost:8123/ENDPOINT"
headers = {
    "Authorization": "Bearer TOKEN",
    "content-type": "application/json",
}

response = get(url, headers=headers)
print(response.text)
```

--------------------------------

### Call Update State API with Curl

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Example of how to call the update state API using curl, providing the state and attributes in the request body.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": "25", "attributes": {"unit_of_measurement": "°C"}}' \
  http://localhost:8123/api/states/sensor.kitchen_temperature
```

--------------------------------

### Call Update State API with Python Requests

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Example of how to call the update state API using the Python Requests module, demonstrating how to set headers and send JSON data.

```python
from requests import post

url = "http://localhost:8123/api/states/sensor.kitchen_temperature"
headers = {"Authorization": "Bearer TOKEN", "content-type": "application/json"}
data = {"state": "25", "attributes": {"unit_of_measurement": "°C"}}

response = post(url, headers=headers, json=data)
print(response.text)
```

--------------------------------

### Get History with URL Encoded Timestamps

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves historical data for a specified period. Ensure timestamps are URL encoded.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/history/period/2021-09-04T00%3A00%3A00%2B02%3A00?end_time=2023-09-04T00%3A00%3A00%2B02%3A00&filter_entity_id=sensor.temperature"
```

--------------------------------

### Get History Period

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves state changes for entities within a specified time period.

```APIDOC
## GET /api/history/period/<timestamp>

### Description
Returns an array of state changes in the past. Each object contains further details for the entities.

The `<timestamp>` (`YYYY-MM-DDThh:mm:ssTZD`) is optional and defaults to 1 day before the time of the request. It determines the beginning of the period.

The following parameters are **required**:

- `filter_entity_id=<entity_ids>` to filter on one or more entities - comma separated.

You can pass the following optional GET parameters:

- `end_time=<timestamp>` to choose the end of the period in URL encoded format (defaults to 1 day).
- `minimal_response` to only return `last_changed` and `state` for states other than the first and last state (much faster).
- `no_attributes` to skip returning attributes from the database (much faster).
- `significant_changes_only` to only return significant state changes.

### Method
GET

### Endpoint
/api/history/period/<timestamp>

### Parameters
#### Path Parameters
- **timestamp** (string) - Optional. The start of the period in `YYYY-MM-DDThh:mm:ssTZD` format. Defaults to 1 day before the request time.

#### Query Parameters
- **filter_entity_id** (string) - Required. Comma-separated list of entity IDs to filter.
- **end_time** (string) - Optional. The end of the period in URL encoded format.
- **minimal_response** (boolean) - Optional. If true, returns only `last_changed` and `state` for non-first/last states.
- **no_attributes** (boolean) - Optional. If true, skips returning attributes.
- **significant_changes_only** (boolean) - Optional. If true, returns only significant state changes.

### Response
#### Success Response (200)
- **entity_id** (string) - The ID of the entity.
- **state** (string) - The state of the entity.
- **last_changed** (string) - The timestamp when the state last changed.
- **last_updated** (string) - The timestamp when the state was last updated.
- **attributes** (object) - Additional attributes of the entity.

### Response Example (without `minimal_response`)
```json
[
    [
        {
            "attributes": {
                "friendly_name": "Weather Temperature",
                "unit_of_measurement": "\u00b0C"
            },
            "entity_id": "sensor.weather_temperature",
            "last_changed": "2016-02-06T22:15:00+00:00",
            "last_updated": "2016-02-06T22:15:00+00:00",
            "state": "-3.9"
        },
        {
            "attributes": {
                "friendly_name": "Weather Temperature",
                "unit_of_measurement": "\u00b0C"
            },
            "entity_id": "sensor.weather_temperature",
            "last_changed": "2016-02-06T22:15:00+00:00",
            "last_updated": "2016-02-06T22:15:00+00:00",
            "state": "-1.9"
        }
    ]
]
```

### Response Example (with `minimal_response`)
```json
[
    [
        {
            "attributes": {
                "friendly_name": "Weather Temperature",
                "unit_of_measurement": "\u00b0C"
            },
            "entity_id": "sensor.weather_temperature",
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/history/period/2016-02-06T22:15:00+00:00?filter_entity_id=sensor.weather_temperature&end_time=2016-02-07T22:15:00+00:00
```
```

--------------------------------

### Get Camera Proxy

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Returns the image data from the specified camera entity ID. An optional `time` query parameter can be provided.

```APIDOC
## GET /api/camera_proxy/<camera entity_id>

### Description
Returns the data (image) from the specified camera `entity_id`.

### Method
GET

### Endpoint
/api/camera_proxy/<camera entity_id>

### Parameters
#### Query Parameters
- **time** (string) - Optional - A timestamp, likely for cache busting or specific frame retrieval.

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -o image.jpg \
  "http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time=1462653861261"
```
```

--------------------------------

### Get Calendar Entities List

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves a list of available calendar entities. Each entry includes the entity ID and a user-friendly name.

```json
[
  {
    "entity_id": "calendar.holidays",
    "name": "National Holidays",
  },
  {
    "entity_id": "calendar.personal",
    "name": "Personal Calendar",
  }
]
```

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8123/api/calendars
```

--------------------------------

### Get Specific State Object

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves a single state object for a given entity ID. Returns 404 if the entity is not found.

```json
{
   "attributes":{
      "azimuth":336.34,
      "elevation":-17.67,
      "friendly_name":"Sun",
      "next_rising":"2016-05-31T03:39:14+00:00",
      "next_setting":"2016-05-31T19:16:42+00:00"
   },
   "entity_id":"sun.sun",
   "last_changed":"2016-05-30T21:43:29.204838+00:00",
   "last_updated":"2016-05-30T21:50:30.529465+00:00",
   "state":"below_horizon"
}
```

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8123/api/states/sensor.kitchen_temperature
```

--------------------------------

### Get Camera Stream Data

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves image data from a specified camera entity ID. The `time` parameter can be used for caching control.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -o image.jpg \
  "http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time=1462653861261"
```

--------------------------------

### Get All States

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Returns an array of state objects for all entities in Home Assistant. Each state object includes entity ID, current state, last changed timestamp, and attributes.

```APIDOC
## GET /api/states

### Description
Returns an array of state objects. Each state has the following attributes: `entity_id`, `state`, `last_changed` and `attributes`.

### Method
GET

### Endpoint
/api/states

### Response
#### Success Response (200)
- **attributes** (object) - An object containing various attributes of the entity.
- **entity_id** (string) - The unique identifier for the entity.
- **last_changed** (string) - The timestamp when the entity's state was last changed.
- **state** (string) - The current state of the entity.

### Response Example
```json
[
    {
        "attributes": {},
        "entity_id": "sun.sun",
        "last_changed": "2016-05-30T21:43:32.418320+00:00",
        "state": "below_horizon"
    },
    {
        "attributes": {},
        "entity_id": "process.Dropbox",
        "last_changed": "22016-05-30T21:43:32.418320+00:00",
        "state": "on"
    }
]
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/states
```
```

--------------------------------

### Get State by Entity ID

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves the state object for a specific entity ID. Returns a 404 error if the entity is not found.

```APIDOC
## GET /api/states/<entity_id>

### Description
Returns a state object for specified `entity_id`. Returns 404 if not found.

### Method
GET

### Endpoint
/api/states/<entity_id>

### Response
#### Success Response (200)
- **attributes** (object) - An object containing various attributes of the entity.
- **entity_id** (string) - The unique identifier for the entity.
- **last_changed** (string) - The timestamp when the entity's state was last changed.
- **last_updated** (string) - The timestamp when the entity was last updated.
- **state** (string) - The current state of the entity.

### Response Example
```json
{
   "attributes":{
      "azimuth":336.34,
      "elevation":-17.67,
      "friendly_name":"Sun",
      "next_rising":"2016-05-31T03:39:14+00:00",
      "next_setting":"2016-05-31T19:16:42+00:00"
   },
   "entity_id":"sun.sun",
   "last_changed":"2016-05-30T21:43:29.204838+00:00",
   "last_updated":"2016-05-30T21:50:30.529465+00:00",
   "state":"below_horizon"
}
```

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8123/api/states/sensor.kitchen_temperature
```
```

--------------------------------

### Get History for a Specific Entity ID

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves the history for a specified entity ID over the past day by default. Requires authentication.

```APIDOC
## GET /api/history/period

### Description
Retrieves the history for a specified entity ID over the past day by default.

### Method
GET

### Endpoint
/api/history/period

### Parameters
#### Query Parameters
- **filter_entity_id** (string) - Required - The entity ID to filter history for (e.g., `sensor.temperature`).

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/history/period?filter_entity_id=sensor.temperature"
```
```

--------------------------------

### Get Historical State Changes (Minimal Response)

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves historical state changes with a minimal response, returning only essential data for states other than the first and last. This is faster for large datasets.

```json
[
    [
        {
            "attributes": {
                "friendly_name": "Weather Temperature",
                "unit_of_measurement": "\u00b0C"
            },
            "entity_id": "sensor.weather_temperature",

```

--------------------------------

### Get All State Objects

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves an array of all state objects. Each object contains entity ID, state, last changed timestamp, and attributes.

```json
[
    {
        "attributes": {},
        "entity_id": "sun.sun",
        "last_changed": "2016-05-30T21:43:32.418320+00:00",
        "state": "below_horizon"
    },
    {
        "attributes": {},
        "entity_id": "process.Dropbox",
        "last_changed": "22016-05-30T21:43:32.418320+00:00",
        "state": "on"
    }
]
```

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" http://localhost:8123/api/states
```

--------------------------------

### Get Default History for an Entity

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves the default history for a specified entity ID. Ensure you replace 'TOKEN' with your actual Home Assistant API token.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/history/period?filter_entity_id=sensor.temperature"
```

--------------------------------

### Get Logbook Entries

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves logbook entries. The timestamp parameter is optional and defaults to 1 day prior. Filters can be applied using entity and end_time parameters.

```json
[
  {
		"context_user_id": null,
		"domain": "alarm_control_panel",
		"entity_id": "alarm_control_panel.area_001",
		"message": "changed to disarmed",
		"name": "Security",
		"when": "2020-06-20T16:44:26.127295+00:00"
	},
	{
		"context_user_id": null,
		"domain": "homekit",
		"entity_id": "alarm_control_panel.area_001",
		"message": "send command alarm_arm_night for Security",
		"name": "HomeKit",
		"when": "2020-06-21T02:59:05.759645+00:00"
	},
	{
		"context_user_id": null,
		"domain": "alarm_control_panel",
		"entity_id": "alarm_control_panel.area_001",
		"message": "changed to armed_night",
		"name": "Security",
		"when": "2020-06-21T02:59:06.015463+00:00"
	}
]
```

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00
```

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00?end_time=2099-12-31T00%3A00%3A00%2B02%3A00&entity=sensor.temperature"
```

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00?end_time=2099-12-31T00%3A00%3A00%2B02%3A00"
```

--------------------------------

### Get History Period

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Retrieves historical data for entities within a specified time period. The timestamp in the URL and the `end_time` parameter should be URL encoded.

```APIDOC
## GET /api/history/period/<timestamp>

### Description
Retrieves historical data for entities within a specified time period. The timestamp in the URL and the `end_time` parameter should be URL encoded.

### Method
GET

### Endpoint
/api/history/period/<timestamp>

### Parameters
#### Query Parameters
- **end_time** (string) - Optional - The end time for the history period, URL encoded.
- **filter_entity_id** (string) - Optional - Filters the history for a specific entity ID.

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/history/period/2021-09-04T00%3A00%3A00%2B02%3A00?end_time=2023-09-04T00%3A00%3A00%2B02%3A00&filter_entity_id=sensor.temperature"
```
```

--------------------------------

### Turn on a light using Python Requests

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

This Python script demonstrates how to turn on a light using the Requests library. It requires the URL, headers with your API token, and a JSON payload specifying the entity.

```python
from requests import post

url = "http://localhost:8123/api/services/light/turn_on"
headers = {"Authorization": "Bearer TOKEN"}
data = {"entity_id": "light.study_light"}

response = post(url, headers=headers, json=data)
print(response.text)
```

--------------------------------

### List Loaded Components

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Returns a list of all components currently loaded within Home Assistant.

```text
[
  "currentcost.sensor",
  "tapo.switch",
  "tuya_ble.sensor",
  "backup",
  "ble_monitor.binary_sensor",
  "localtuya.remote",
  "logger",
  "http",
  "hacs",
  "cast",
  "device_tracker",
  "upnp.binary_sensor",
  "notify",
  "person",
  ...
]
```

--------------------------------

### Turn on a light using curl

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Use this endpoint to control lights. Ensure you replace 'TOKEN' with your actual API token.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "switch.christmas_lights"}' \
  http://localhost:8123/api/services/switch/turn_on
```

--------------------------------

### Handle an intent

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Send an intent to Home Assistant for processing. Ensure you have `intent:` enabled in your `configuration.yaml`.

```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "SetTimer", "data": { "seconds": "30" } }' \
  http://localhost:8123/api/intent/handle
```

--------------------------------

### Configure RESTful Command Integration

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

Define a RESTful command in Home Assistant's configuration.yaml to control devices, such as turning a light on. This requires a valid access token and correct endpoint.

```yaml
turn_light_on:
  url: http://localhost:8123/api/states/light.study_light
  method: POST
  headers:
    authorization: 'Bearer TOKEN'
    content-type: 'application/json'
  payload: '{"state":"on"}'
```

--------------------------------

### Handle intent

Source: https://raw.githubusercontent.com/home-assistant/developers.home-assistant/refs/heads/master/docs/api/rest.md

This endpoint handles intents. You must enable the `intent:` integration in your `configuration.yaml` to use this endpoint.

```APIDOC
## POST /api/intent/handle

### Description
Handles an intent. Ensure that `intent:` is configured in your `configuration.yaml`.

### Method
POST

### Endpoint
/api/intent/handle

### Parameters
#### Request Body
- **name** (string) - Required - The name of the intent to handle.
- **data** (object) - Optional - Data associated with the intent.
  - **seconds** (string) - Example parameter for setting a timer.

### Request Example
```shell
curl \
  -H "Authorization: Bearer TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "SetTimer", "data": { "seconds": "30" } }' \
  http://localhost:8123/api/intent/handle
```
```
Tokens:
Raw