Skip to content

Instantly share code, notes, and snippets.

@oleander

oleander/spec.yml

Created March 2, 2025 01:03
Show Gist options
  • Save oleander/0469f8c69e7434d49360693ee7225b9a to your computer and use it in GitHub Desktop.
Save oleander/0469f8c69e7434d49360693ee7225b9a to your computer and use it in GitHub Desktop.
Download ZIP
Home Assistant OpenAPI 3.1 REST API
Raw
spec.yml
openapi: 3.1.0
info:
title: Home Assistant REST API
version: 1.0.0
description: |
Official Home Assistant REST API specification based on documentation.
Authentication requires a Long-Lived Access Token that can be generated from the Home Assistant profile page.
All API calls must use the Bearer token in the Authorization header.
**CURL usage example:**
```bash
curl -X GET \
-H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
http://localhost:8123/api/states
```
**Note about timestamp path parameters**:
For endpoints with path parameters like `/history/period/{timestamp}` and `/logbook/{timestamp}`,
the API defaults to "1 day before the request time" if the parameter is omitted.
Since OpenAPI 3.1 doesn't support optional path parameters, we've included alternative routes
without the timestamp parameter (e.g., `/history/period` and `/logbook`).
**API Versioning Strategy**:
The Home Assistant REST API uses a versioning strategy based on the Home Assistant core version.
Breaking changes to the API are avoided when possible, but when necessary, they are communicated
in the release notes of the corresponding Home Assistant version.
While the API doesn't include explicit version numbers in the paths (like `/v1/states`), clients
should check the Home Assistant version through the `/config` endpoint to determine compatibility.
The current API specification is aligned with Home Assistant version 2023.3 and newer.
contact:
name: Home Assistant Developers
url: https://developers.home-assistant.io/docs/api/rest/
x-api-version: "1.0.0"
x-ha-min-version: "2023.3.0"
servers:
- url: http://IP_ADDRESS:8123/api
description: Home Assistant API Server
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: token
description: |
Authentication uses a Long-Lived Access Token that can be generated from the Home Assistant profile page.
To create a token:
1. Log in to your Home Assistant instance
2. Click on your profile (bottom left)
3. Scroll to the bottom of the page
4. Under "Long-Lived Access Tokens", click "Create Token"
5. Give your token a name and click "OK"
6. Copy the token immediately (it won't be shown again)
Tokens have no expiration date but can be revoked from the same profile page.
All API requests must include this token in the Authorization header:
`Authorization: Bearer YOUR_TOKEN`
Requests without a valid token will receive a 401 Unauthorized response.
# Optional: For future OAuth 2.0 support (not currently implemented)
# oauth2Auth:
# type: oauth2
# flows:
# authorizationCode:
# authorizationUrl: https://your-instance.com/auth/authorize
# tokenUrl: https://your-instance.com/auth/token
# scopes:
# read: Read access to Home Assistant
# write: Write access to Home Assistant
parameters:
EntityIdParam:
name: entity_id
in: path
required: true
description: ID of the entity (format domain.entity, e.g. light.kitchen)
schema:
type: string
example: "light.living_room"
TimestampParam:
name: timestamp
in: path
required: true
description: ISO 8601 formatted timestamp (e.g., 2023-01-01T00:00:00Z)
schema:
type: string
format: date-time
example: "2023-01-01T00:00:00Z"
EndTimeParam:
name: end_time
in: query
required: false
description: The end of the period in ISO 8601 format. If not specified, the current time will be used.
schema:
type: string
format: date-time
example: "2023-01-01T23:59:59Z"
ReturnResponseParam:
name: return_response
in: query
required: false
description: When set to true, includes service response data in the result
schema:
type: boolean
default: false
PaginationLimitParam:
name: limit
in: query
required: false
description: Maximum number of items to return in the response. Default varies by endpoint.
schema:
type: integer
minimum: 1
default: 100
PaginationOffsetParam:
name: offset
in: query
required: false
description: Number of items to skip before starting to collect the result set.
schema:
type: integer
minimum: 0
default: 0
FilterEntityIdParam:
name: filter_entity_id
in: query
required: false
description: One or more entity IDs to filter on, comma separated. If not specified, all entities are included.
schema:
type: string
example: "light.living_room,sensor.temperature"
EntityParam:
name: entity
in: query
required: false
description: Filter on one entity. If not specified, all entities are included.
schema:
type: string
example: "light.living_room"
PeriodParam:
name: period
in: query
required: false
description: Number of days to include in the response. Default is 1 day.
schema:
type: integer
default: 1
minimum: 1
EventTypeParam:
name: event_type
in: path
required: true
description: Type of the event to trigger
schema:
type: string
example: "call_service"
headers:
AcceptHeader:
description: Specifies the expected format of the response
schema:
type: string
enum:
- application/json
- text/plain
example: application/json
ContentTypeHeader:
description: Specifies the format of the request body
schema:
type: string
enum:
- application/json
default: application/json
example: application/json
AuthorizationHeader:
description: Contains the bearer token for authentication
schema:
type: string
pattern: '^Bearer [A-Za-z0-9-._~+/]+=*$'
example: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
schemas:
State:
type: object
properties:
entity_id:
type: string
description: ID of the entity
state:
type: string
description: Current state of the entity
attributes:
type: object
description: Entity attributes
last_changed:
type: string
format: date-time
description: Timestamp when the state was last changed
last_updated:
type: string
format: date-time
description: Timestamp when the state was last updated
context:
$ref: "#/components/schemas/Context"
ConfigResponse:
type: object
properties:
components:
type: array
description: List of loaded components
items:
type: string
config_dir:
type: string
description: Configuration directory path
elevation:
type: number
description: Elevation
latitude:
type: number
description: Latitude
longitude:
type: number
description: Longitude
location_name:
type: string
description: Name of the location
time_zone:
type: string
description: Time zone
unit_system:
type: object
properties:
length:
type: string
mass:
type: string
temperature:
type: string
volume:
type: string
version:
type: string
description: Home Assistant version
EventObject:
type: object
properties:
event:
type: string
description: Name of the event
listener_count:
type: integer
description: Number of event listeners
HistoryStateChange:
type: object
properties:
entity_id:
type: string
description: Entity ID
state:
type: string
description: State value
attributes:
type: object
description: State attributes
last_changed:
type: string
format: date-time
description: Last time the state changed
last_updated:
type: string
format: date-time
description: Last time the state was updated
LogbookEntry:
type: object
properties:
entity_id:
type: string
description: Entity ID
state:
type: string
description: State
when:
type: string
format: date-time
description: When the event occurred
name:
type: string
description: Name of the entity
message:
type: string
description: Message describing the event
domain:
type: string
description: Domain of the entity
icon:
type: string
description: Icon of the entity
Service:
type: object
properties:
domain:
type: string
description: Domain of the service
services:
type: object
additionalProperties:
type: object
properties:
description:
type: string
fields:
type: object
additionalProperties:
type: object
properties:
description:
type: string
example:
type: string
CalendarObject:
type: object
properties:
entity_id:
type: string
description: Entity ID
name:
type: string
description: Name of the calendar
CalendarEvent:
type: object
properties:
summary:
type: string
description: Summary of the event
start:
type: string
format: date-time
description: Start time of the event
end:
type: string
format: date-time
description: End time of the event
description:
type: string
description: Description of the event
location:
type: string
description: Location of the event
uid:
type: string
description: Unique ID of the event
ErrorResponse:
type: object
required:
- message
properties:
message:
type: string
description: Human-readable error message explaining what went wrong
code:
type: string
description: Optional error code identifier that can be used for client-side error handling
examples:
unauthorized:
value:
message: "Unauthorized"
entity_not_found:
value:
message: "Entity not found."
invalid_state:
value:
message: "Invalid state specified."
service_not_found:
value:
message: "Service not found."
code: "not_found"
Context:
type: object
description: Context information for state changes and events
properties:
id:
type: string
description: Context ID
parent_id:
type: string
description: Parent context ID
user_id:
type: string
description: User ID
Error:
$ref: "#/components/schemas/ErrorResponse"
ServiceRequestBody:
type: object
description: Generic service call request body
properties:
entity_id:
type: string
description: Entity ID or comma-separated IDs to target
additionalProperties: true
examples:
turn_on_light:
value: {
"entity_id": "light.living_room",
"brightness": 255,
"color_name": "blue"
}
set_climate:
value: {
"entity_id": "climate.living_room",
"temperature": 22.5,
"hvac_mode": "heat"
}
reload_config:
value: {}
ServiceResponse:
type: object
description: Object containing changed states and service response (when return_response=true)
properties:
changed_states:
type: array
description: States that changed as a result of the service call
items:
$ref: "#/components/schemas/State"
service_response:
type: object
description: Response returned by the service
additionalProperties: true
MessageResponse:
type: object
description: Simple message response
properties:
message:
type: string
description: Response message
paths:
/:
get:
summary: Check API status
description: |
Returns a message if the API is up and running. This endpoint serves as a basic health check
to verify that the Home Assistant API is accessible and responding to requests.
This is useful for:
- Verifying authentication token validity
- Checking if the Home Assistant instance is online
- Testing API connectivity before making more complex requests
No additional parameters are required for this endpoint.
operationId: APIStatus
responses:
200:
description: API is running
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: API running.
examples:
success:
value:
message: "API running."
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
unauthorized:
value:
message: "Unauthorized"
security:
- bearerAuth: []
/config:
get:
summary: Retrieve current configuration
description: |
Returns the current configuration settings of your Home Assistant instance.
This endpoint provides essential details about how your Home Assistant instance is configured, including:
- Geographic location (latitude, longitude, elevation)
- Time zone settings
- Unit system preferences
- Home Assistant version
- List of loaded components
- Configuration directory path
This information is useful for clients that need to adapt their behavior based on system settings,
such as displaying temperature in the correct unit format or localizing time data.
**Version Compatibility Check**:
API clients should use this endpoint to check the Home Assistant version (`version` field)
to determine compatibility with their implementation. This is especially important after
Home Assistant upgrades, as some API behaviors may change between versions.
```
// Example version compatibility check in JavaScript
fetch('/api/config')
.then(response => response.json())
.then(config => {
// Compare with minimum supported version
if (isVersionAtLeast(config.version, '2023.3.0')) {
// Use features available in 2023.3.0 and later
} else {
// Use legacy approach
}
});
```
No request parameters are needed to access this endpoint.
operationId: APIConfig
responses:
200:
description: Current configuration details
content:
application/json:
schema:
$ref: "#/components/schemas/ConfigResponse"
examples:
success:
value: {
"components": ["automation", "config", "frontend", "history", "homeassistant", "light", "media_player", "sensor", "sun", "weather"],
"config_dir": "/config",
"elevation": 358,
"latitude": 37.5485,
"longitude": -121.9886,
"location_name": "Home",
"time_zone": "America/Los_Angeles",
"unit_system": {
"length": "km",
"mass": "kg",
"temperature": "°C",
"volume": "L"
},
"version": "2023.3.6"
}
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
unauthorized:
value:
message: "Unauthorized"
security:
- bearerAuth: []
/states:
get:
summary: Retrieve all states
description: |
Returns the current state of all entities in Home Assistant.
This endpoint provides a complete snapshot of the current state of your home automation system,
including all entities (devices, sensors, automations, etc.) and their attributes.
Use cases include:
- Building dashboards that display the status of all entities
- Performing batch operations based on multiple entity states
- Synchronizing external systems with Home Assistant's state
The response is an array of state objects containing entity IDs, current states, attributes,
and timestamp information.
No request parameters are needed to access this endpoint.
operationId: GetAllStates
parameters:
- $ref: "#/components/parameters/PaginationLimitParam"
- $ref: "#/components/parameters/PaginationOffsetParam"
responses:
200:
description: List of all entity states
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/State"
examples:
success:
value: [
{
"entity_id": "light.living_room",
"state": "on",
"attributes": {
"brightness": 255,
"friendly_name": "Living Room Light",
"supported_features": 41
},
"last_changed": "2023-04-01T12:34:56.789Z",
"last_updated": "2023-04-01T12:34:56.789Z",
"context": {
"id": "01EXAMPLEID1234567890",
"parent_id": null,
"user_id": "abcdefghijklmnopqrstuvwxyz"
}
},
{
"entity_id": "sensor.temperature",
"state": "22.5",
"attributes": {
"unit_of_measurement": "°C",
"friendly_name": "Temperature Sensor",
"device_class": "temperature"
},
"last_changed": "2023-04-01T12:30:00.000Z",
"last_updated": "2023-04-01T12:30:00.000Z",
"context": {
"id": "01EXAMPLEID1234567891",
"parent_id": null,
"user_id": null
}
}
]
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
unauthorized:
value:
message: "Unauthorized"
security:
- bearerAuth: []
/states/{entity_id}:
get:
summary: Retrieve state of a specific entity
description: |
Returns the current state of a specific entity identified by its entity_id.
This endpoint provides detailed information about a single entity, including its:
- Current state value
- All attributes
- Last changed and updated timestamps
- Context information
This is useful when you need focused information about a specific entity rather than
the entire system state. Common use cases include:
- Checking if a specific device is on/off
- Reading sensor values
- Getting detailed attributes of a specific entity
If the entity doesn't exist, a 404 error is returned.
operationId: GetEntityState
parameters:
- $ref: "#/components/parameters/EntityIdParam"
responses:
200:
description: State details of the specified entity
content:
application/json:
schema:
$ref: "#/components/schemas/State"
examples:
light:
value: {
"entity_id": "light.living_room",
"state": "on",
"attributes": {
"brightness": 255,
"friendly_name": "Living Room Light",
"supported_features": 41
},
"last_changed": "2023-04-01T12:34:56.789Z",
"last_updated": "2023-04-01T12:34:56.789Z",
"context": {
"id": "01EXAMPLEID1234567890",
"parent_id": null,
"user_id": "abcdefghijklmnopqrstuvwxyz"
}
}
sensor:
value: {
"entity_id": "sensor.temperature",
"state": "22.5",
"attributes": {
"unit_of_measurement": "°C",
"friendly_name": "Temperature Sensor",
"device_class": "temperature"
},
"last_changed": "2023-04-01T12:30:00.000Z",
"last_updated": "2023-04-01T12:30:00.000Z",
"context": {
"id": "01EXAMPLEID1234567891",
"parent_id": null,
"user_id": null
}
}
404:
description: Entity not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
not_found:
value:
message: "Entity not found."
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
unauthorized:
value:
message: "Unauthorized"
security:
- bearerAuth: []
post:
summary: Update or create state of a specific entity
description: |
Updates the state of an existing entity or creates a new entity with the specified state.
This endpoint allows you to:
- Set the state value of an entity
- Update entity attributes
- Force an update even when the state hasn't changed
This is particularly useful for:
- Creating custom entities not managed by integrations
- Updating states from external systems
- Setting virtual entities for UI or automation purposes
Note that creating entities this way does not register them with integrations or make them
controllable - they are primarily for state representation. For actual device control,
use the services API endpoints.
Returns 200 if the state was updated or 201 if a new entity was created.
operationId: UpdateEntityState
parameters:
- in: path
name: entity_id
required: true
description: ID of the entity to update or create
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
state:
type: string
description: The new state value
attributes:
type: object
description: State attributes to set
force_update:
type: boolean
description: Force an update even if the state hasn't changed
required:
- state
examples:
simple:
value: {
"state": "on"
}
with_attributes:
value: {
"state": "25.6",
"attributes": {
"unit_of_measurement": "°C",
"friendly_name": "Outside Temperature"
}
}
force_update:
value: {
"state": "home",
"attributes": {
"friendly_name": "User Presence"
},
"force_update": true
}
responses:
200:
description: State updated successfully
content:
application/json:
schema:
$ref: "#/components/schemas/State"
examples:
updated:
value: {
"entity_id": "sensor.external_temp",
"state": "25.6",
"attributes": {
"unit_of_measurement": "°C",
"friendly_name": "Outside Temperature"
},
"last_changed": "2023-04-01T12:34:56.789Z",
"last_updated": "2023-04-01T12:34:56.789Z",
"context": {
"id": "01EXAMPLEID1234567890",
"parent_id": null,
"user_id": "abcdefghijklmnopqrstuvwxyz"
}
}
201:
description: State created successfully
content:
application/json:
schema:
$ref: "#/components/schemas/State"
examples:
created:
value: {
"entity_id": "input_boolean.custom_flag",
"state": "on",
"attributes": {
"friendly_name": "Custom Flag"
},
"last_changed": "2023-04-01T12:34:56.789Z",
"last_updated": "2023-04-01T12:34:56.789Z",
"context": {
"id": "01EXAMPLEID1234567890",
"parent_id": null,
"user_id": "abcdefghijklmnopqrstuvwxyz"
}
}
400:
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
missing_state:
value:
message: "No state specified."
invalid_state:
value:
message: "Invalid state specified."
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
unauthorized:
value:
message: "Unauthorized"
security:
- bearerAuth: []
delete:
summary: Delete an entity
description: |
Removes an entity from Home Assistant.
This endpoint allows you to delete entities that were created through the API.
Note that this only works for entities created via the API, not for entities registered
by integrations or components. Attempting to delete an integrated entity will result
in an error.
Use cases include:
- Cleaning up custom entities that are no longer needed
- Removing temporary entities created for specific purposes
- Managing virtual/custom entities lifecycle
If the entity doesn't exist, a 404 error is returned.
operationId: DeleteEntity
parameters:
- in: path
name: entity_id
required: true
description: ID of the entity to delete
schema:
type: string
responses:
200:
description: Entity removed successfully
content:
application/json:
schema:
$ref: "#/components/schemas/MessageResponse"
examples:
success:
value:
message: "Entity removed."
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
unauthorized:
value:
message: "Unauthorized"
404:
description: Entity not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
not_found:
value:
message: "Entity not found."
security:
- bearerAuth: []
/services/{domain}/{service}:
post:
summary: Call a service within a specific domain
description: |
Calls a service in Home Assistant with the specified parameters.
This endpoint is one of the most powerful in the Home Assistant API, as it allows
you to execute actions and control devices. Services are organized by domains, which
typically correspond to integrations or components.
Common use cases include:
- Turning devices on or off (e.g., domain: "light", service: "turn_on")
- Adjusting settings like brightness, temperature, or volume
- Triggering automations or scenes
- Running system operations like restarts or database cleanups
The request body typically includes an "entity_id" field to specify the target entity,
but can also include other service-specific parameters. You can find the available
services and their parameters in the Home Assistant Developer Tools > Services panel.
When calling a service, you can optionally request the service response using the
"return_response" query parameter. This is useful for services that return data.
The response will include states that changed as a result of the service call, and
optionally the service response if requested.
operationId: CallService
parameters:
- name: domain
in: path
required: true
description: Domain of the service (e.g., light, switch, automation)
schema:
type: string
- name: service
in: path
required: true
description: Name of the service (e.g., turn_on, turn_off)
schema:
type: string
- $ref: "#/components/parameters/ReturnResponseParam"
requestBody:
required: false
content:
application/json:
schema:
$ref: "#/components/schemas/ServiceRequestBody"
responses:
200:
description: Service called successfully
content:
application/json:
schema:
oneOf:
- type: array
description: Array of changed states (when return_response is not used)
items:
$ref: "#/components/schemas/State"
- $ref: "#/components/schemas/ServiceResponse"
examples:
changed_states:
value: [
{
"entity_id": "light.living_room",
"state": "on",
"attributes": {
"brightness": 255,
"color_name": "blue",
"friendly_name": "Living Room Light",
"supported_features": 41
},
"last_changed": "2023-04-01T12:34:56.789Z",
"last_updated": "2023-04-01T12:34:56.789Z",
"context": {
"id": "01EXAMPLEID1234567890",
"parent_id": null,
"user_id": "abcdefghijklmnopqrstuvwxyz"
}
}
]
with_response:
value: {
"changed_states": [
{
"entity_id": "climate.living_room",
"state": "heat",
"attributes": {
"temperature": 22.5,
"current_temperature": 20.0,
"friendly_name": "Living Room Thermostat",
"supported_features": 17
},
"last_changed": "2023-04-01T12:34:56.789Z",
"last_updated": "2023-04-01T12:34:56.789Z",
"context": {
"id": "01EXAMPLEID1234567890",
"parent_id": null,
"user_id": "abcdefghijklmnopqrstuvwxyz"
}
}
],
"service_response": {
"status": "success",
"processing_time": 0.23
}
}
400:
description: Bad request, invalid service or parameters
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
invalid_parameters:
value:
message: "Invalid JSON specified."
schema_validation:
value:
message: "Invalid service parameter brightness: expected float for dictionary value @ data['brightness']"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
unauthorized:
value:
message: "Unauthorized"
404:
description: Service or domain not found
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
not_found:
value:
message: "Service not found."
security:
- bearerAuth: []
/events:
get:
summary: Get all event listeners
description: |
Returns a list of all event types and their listener counts in Home Assistant.
This endpoint provides information about the event system, which is one of the core
mechanisms in Home Assistant. Events are triggered by various components and can be
listened to by automations, scripts, and other components.
Use cases include:
- Debugging and troubleshooting event-driven automations
- Understanding which events are available in your system
- Monitoring the number of listeners for performance analysis
The response contains an array of event objects, each with the event name and the
number of registered listeners.
No request parameters are needed to access this endpoint.
operationId: Events
parameters:
- $ref: "#/components/parameters/PaginationLimitParam"
- $ref: "#/components/parameters/PaginationOffsetParam"
responses:
200:
description: List of event listeners
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/EventObject"
examples:
success:
value: [
{
"event": "state_changed",
"listener_count": 24
},
{
"event": "homeassistant_start",
"listener_count": 12
},
{
"event": "automation_triggered",
"listener_count": 3
},
{
"event": "custom_event",
"listener_count": 1
}
]
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
unauthorized:
value:
message: "Unauthorized"
security:
- bearerAuth: []
/history/period:
get:
summary: Get historical state changes with default time range
description: |
Returns historical state changes for the past day (by default).
This endpoint provides access to historical entity state data, which is useful for:
- Generating graphs and trends of sensor values over time
- Reviewing when devices were turned on/off
- Analyzing patterns in system behavior
By default, this endpoint returns data from 1 day before the request time to the current time.
The response is organized as an array of arrays, where each inner array contains state changes
for a specific entity.
You can filter the results to specific entities, modify the response format for optimization,
specify an end time, and control whether to include all changes or only significant ones.
Note: This endpoint requires the History integration to be enabled in Home Assistant.
operationId: HistoryPeriodDefault
parameters:
- $ref: "#/components/parameters/FilterEntityIdParam"
- $ref: "#/components/parameters/EndTimeParam"
- name: minimal_response
in: query
required: false
description: Only return last_changed and state for states other than the first and last state.
schema:
type: boolean
default: false
- name: no_attributes
in: query
required: false
description: Skip returning attributes from the database.
schema:
type: boolean
default: false
- name: significant_changes_only
in: query
required: false
description: Only return significant state changes.
schema:
type: boolean
default: true
- $ref: "#/components/parameters/PaginationLimitParam"
responses:
200:
description: Array of state changes in the past.
content:
application/json:
schema:
type: array
items:
type: array
items:
$ref: "#/components/schemas/HistoryStateChange"
examples:
success:
value: [
[
{
"entity_id": "sensor.temperature",
"state": "21.5",
"attributes": {
"unit_of_measurement": "°C",
"friendly_name": "Temperature"
},
"last_changed": "2023-04-01T10:00:00.000Z",
"last_updated": "2023-04-01T10:00:00.000Z"
},
{
"entity_id": "sensor.temperature",
"state": "22.0",
"attributes": {
"unit_of_measurement": "°C",
"friendly_name": "Temperature"
},
"last_changed": "2023-04-01T11:00:00.000Z",
"last_updated": "2023-04-01T11:00:00.000Z"
}
],
[
{
"entity_id": "light.living_room",
"state": "off",
"attributes": {
"friendly_name": "Living Room Light",
"supported_features": 41
},
"last_changed": "2023-04-01T08:00:00.000Z",
"last_updated": "2023-04-01T08:00:00.000Z"
},
{
"entity_id": "light.living_room",
"state": "on",
"attributes": {
"brightness": 255,
"friendly_name": "Living Room Light",
"supported_features": 41
},
"last_changed": "2023-04-01T18:00:00.000Z",
"last_updated": "2023-04-01T18:00:00.000Z"
}
]
]
400:
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
invalid_datetime:
value:
message: "Invalid end_time"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
unauthorized:
value:
message: "Unauthorized"
security:
- bearerAuth: []
/history/period/{timestamp}:
get:
summary: Get historical state changes with specific start time
description: |
Returns historical state changes starting from a specific timestamp.
This endpoint functions similarly to `/history/period` but allows you to specify
the exact start time instead of using the default 1-day lookback. This is useful for:
- Getting historical data from a specific date
- Creating reports for custom time ranges
- Analyzing data from a particular event onwards
The timestamp parameter specifies the beginning of the period in ISO 8601 format.
Like the default history endpoint, you can filter entities, specify an end time,
and optimize the response format using query parameters.
Note: This endpoint requires the History integration to be enabled in Home Assistant.
operationId: HistoryPeriod
parameters:
- $ref: "#/components/parameters/TimestampParam"
- $ref: "#/components/parameters/FilterEntityIdParam"
- $ref: "#/components/parameters/EndTimeParam"
- name: minimal_response
in: query
required: false
description: Only return last_changed and state for states other than the first and last state.
schema:
type: boolean
default: false
- name: no_attributes
in: query
required: false
description: Skip returning attributes from the database.
schema:
type: boolean
default: false
- name: significant_changes_only
in: query
required: false
description: Only return significant state changes.
schema:
type: boolean
default: true
responses:
200:
description: Array of state changes in the past.
content:
application/json:
schema:
type: array
items:
type: array
items:
$ref: "#/components/schemas/HistoryStateChange"
examples:
success:
value: [
[
{
"entity_id": "sensor.temperature",
"state": "21.5",
"attributes": {
"unit_of_measurement": "°C",
"friendly_name": "Temperature"
},
"last_changed": "2023-01-01T00:30:00.000Z",
"last_updated": "2023-01-01T00:30:00.000Z"
},
{
"entity_id": "sensor.temperature",
"state": "22.0",
"attributes": {
"unit_of_measurement": "°C",
"friendly_name": "Temperature"
},
"last_changed": "2023-01-01T01:15:00.000Z",
"last_updated": "2023-01-01T01:15:00.000Z"
}
],
[
{
"entity_id": "light.living_room",
"state": "off",
"attributes": {
"friendly_name": "Living Room Light",
"supported_features": 41
},
"last_changed": "2023-01-01T00:00:00.000Z",
"last_updated": "2023-01-01T00:00:00.000Z"
},
{
"entity_id": "light.living_room",
"state": "on",
"attributes": {
"brightness": 255,
"friendly_name": "Living Room Light",
"supported_features": 41
},
"last_changed": "2023-01-01T07:30:00.000Z",
"last_updated": "2023-01-01T07:30:00.000Z"
}
]
]
400:
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
invalid_timestamp:
value:
message: "Invalid datetime"
invalid_end_time:
value:
message: "Invalid end_time"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
unauthorized:
value:
message: "Unauthorized"
security:
- bearerAuth: []
/logbook:
get:
summary: Get logbook entries with default time range
description: |
Returns logbook entries for the past day (by default).
The logbook provides a chronological list of events and state changes that have occurred
in your Home Assistant instance. Unlike the history endpoint which focuses on state changes
for specific entities, the logbook provides a unified timeline
operationId: LogbookEntriesDefault
parameters:
- $ref: "#/components/parameters/EntityParam"
- $ref: "#/components/parameters/EndTimeParam"
- $ref: "#/components/parameters/PeriodParam"
- $ref: "#/components/parameters/PaginationLimitParam"
responses:
200:
description: Array of logbook entries.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/LogbookEntry"
400:
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/logbook/{timestamp}:
get:
summary: Get logbook entries with specific start time
description: |
Returns an array of logbook entries starting from the specified timestamp.
**Example:**
```bash
curl -X GET \
-H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
http://localhost:8123/api/logbook/2023-01-01T00:00:00Z
```
operationId: LogbookEntries
parameters:
- $ref: "#/components/parameters/TimestampParam"
- $ref: "#/components/parameters/EntityParam"
- $ref: "#/components/parameters/EndTimeParam"
- $ref: "#/components/parameters/PeriodParam"
- $ref: "#/components/parameters/PaginationLimitParam"
responses:
200:
description: Array of logbook entries.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/LogbookEntry"
400:
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/error_log:
get:
summary: Get error log
description: Retrieve all errors logged during the current session of Home Assistant as a plaintext response.
operationId: GetErrorLog
responses:
200:
description: Plaintext response containing all logged errors.
content:
text/plain:
schema:
type: string
example: |
2024-02-29 12:34:56 ERROR (MainThread) [homeassistant.components.sensor] Unable to parse data from sensor
2024-02-29 12:36:22 WARNING (MainThread) [homeassistant.loader] Failed to load component zwave_js
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/camera_proxy/{entity_id}:
get:
summary: Get camera image
description: Returns the data (image) from the specified camera entity_id.
operationId: GetCameraData
parameters:
- $ref: "#/components/parameters/EntityIdParam"
- name: width
in: query
required: false
description: Width of the image in pixels
schema:
type: integer
- name: height
in: query
required: false
description: Height of the image in pixels
schema:
type: integer
responses:
200:
description: Camera image data
content:
image/jpeg:
schema:
type: string
format: binary
contentEncoding: binary
image/png:
schema:
type: string
format: binary
contentEncoding: binary
400:
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
404:
description: Camera not found
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/calendars:
get:
summary: Get list of calendars
description: Returns the list of calendar entities
operationId: GetCalendars
parameters:
- $ref: "#/components/parameters/PaginationLimitParam"
- $ref: "#/components/parameters/PaginationOffsetParam"
responses:
200:
description: List of calendar entities
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/CalendarObject"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/calendars/{entity_id}:
get:
summary: Get calendar events
description: Returns the list of calendar events for the specified calendar entity_id between the start and end times (exclusive).
operationId: GetCalendarEvents
parameters:
- $ref: "#/components/parameters/EntityIdParam"
- name: start
in: query
required: true
description: Start time of the events in YYYY-MM-DDThh:mm:ssTZD format
schema:
type: string
format: date-time
- name: end
in: query
required: true
description: End time of the events in YYYY-MM-DDThh:mm:ssTZD format
schema:
type: string
format: date-time
responses:
200:
description: List of calendar events
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/CalendarEvent"
400:
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
404:
description: Calendar not found
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/events/{event_type}:
post:
summary: Fire event
description: |
Fires an event with event_type. Some events require specific data, while others accept optional event data.
Refer to the Home Assistant documentation for specific event requirements.
operationId: FireEvent
parameters:
- $ref: "#/components/parameters/EventTypeParam"
requestBody:
required: false
description: Event data (varies based on event type)
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
200:
description: Event fired
content:
application/json:
schema:
$ref: "#/components/schemas/MessageResponse"
examples:
success:
value:
message: "Event my_event fired."
400:
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/template:
post:
summary: Render template
description: |
Render a Home Assistant template. See template docs for more information.
**Example:**
```bash
curl -X POST \
-H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "{{ states(\"sensor.temperature\") }}"}' \
http://localhost:8123/api/template
```
operationId: RenderTemplate
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
template:
type: string
description: The template string to render
example: '{{ states("sensor.temperature") }}'
required:
- template
responses:
200:
description: Returns the rendered template in plain text.
content:
text/plain:
schema:
type: string
400:
description: Bad request (invalid template)
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/config/core/check_config:
post:
summary: Check configuration
description: Trigger a check of configuration.yaml. No additional data needs to be passed in with this request. Needs config integration enabled.
operationId: CheckConfig
responses:
200:
description: Configuration check results
content:
application/json:
schema:
type: object
properties:
errors:
description: Contains error information if validation failed, null if successful
oneOf:
- type: "null"
- type: string
- type: array
items:
type: string
result:
type: string
enum:
- valid
- invalid
description: Result of the configuration check
400:
description: Bad request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/intent/handle:
post:
summary: Handle intent
description: Handle an intent.
operationId: HandleIntent
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
intent:
type: string
description: The intent to handle
example: "HassLightTurnOn"
slots:
type: object
description: Optional slots to fill intent parameters
required:
- intent
responses:
200:
description: Returns the response for the handled intent.
content:
application/json:
schema:
type: object
properties:
speech:
type: object
properties:
plain:
type: string
description: Speech response in plain text
response_type:
type: string
description: Type of response
enum:
- action_done
- error
400:
description: Bad request (invalid intent)
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/services:
get:
summary: Get all available services
description: Returns a list of available services
operationId: GetServices
responses:
200:
description: List of services
content:
application/json:
schema:
type: object
additionalProperties:
$ref: "#/components/schemas/Service"
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/components:
get:
summary: Get all loaded components
description: Returns a list of all loaded components
operationId: GetComponents
responses:
200:
description: List of loaded components
content:
application/json:
schema:
type: array
items:
type: string
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/core/state:
get:
summary: Get core state
description: Returns the current state of the Home Assistant core
operationId: GetCoreState
responses:
200:
description: Core state information
content:
application/json:
schema:
type: object
properties:
state:
type: string
description: Current state of the Home Assistant core
enum:
- starting
- running
- stopping
- final_write
- stopped
recorder_state:
type: object
properties:
migration_in_progress:
type: boolean
description: Whether a database migration is in progress
migration_is_live:
type: boolean
description: Whether the migration is affecting live data
401:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment