developers.home-assistant.io Open in urlscan Pro
2606:4700:20::ac43:445a  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Skip to main content

Developers
Home Assistant
 * Overview
 * Core
 * Frontend
 * Supervisor
 * Add-ons
 * Operating System
 * Voice
 * Translations

MiscBlog
ctrlK

 * Introduction
 * Architecture
 * Development Workflow
 * Building Integrations
 * Development Checklist
 * The `hass` object
 * Entities
 * Areas, Devices and Entities
 * Authentication
 * Config Entries
 * Data Entry Flow
 * Device Automations
 * Intents
 * Conversation
 * Native App Integration
 * Brands
 * Application Credentials
 * Backup
 * Raising Exceptions
 * Repairs
 * Reproduce State
 * Significant Change
 * External APIs
   * WebSocket API
   * REST API
 * Misc

 * 
 * External APIs
 * REST API

On this page


REST API

Home Assistant provides a RESTful API on the same port as the web frontend
(default port is port 8123).

If you are not using the frontend in your setup then you need to add the api
integration to your configuration.yaml file.

 * http://IP_ADDRESS:8123/ is an interface to control Home Assistant.
 * http://IP_ADDRESS:8123/api/ is a RESTful API.

The API accepts and returns only JSON encoded objects.

All API calls have to be accompanied by the header Authorization: Bearer TOKEN,
where TOKEN is replaced by your unique access token. You obtain a token
("Long-Lived Access Token") by logging into the frontend using a web browser,
and going to your profile http://IP_ADDRESS:8123/profile. Be careful to copy the
whole key.

There are multiple ways to consume the Home Assistant Rest API. One is with
curl:

curl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  http://IP_ADDRESS:8123/ENDPOINT




Another option is to use Python and the Requests module.

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)




Another option is to use the RESTful Command integration in a Home Assistant
automation or script.

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"}'




Successful calls will return status code 200 or 201. Other status codes that can
return are:

 * 400 (Bad Request)
 * 401 (Unauthorized)
 * 404 (Not Found)
 * 405 (Method Not Allowed)


ACTIONS

The API supports the following actions:

get
/api/
🔒
get
/api/config
🔒
get
/api/events
🔒
get
/api/services
🔒
get
/api/history/period/<timestamp>
🔒
get
/api/logbook/<timestamp>
🔒
get
/api/states
🔒
get
/api/states/<entity_id>
🔒
get
/api/error_log
🔒
get
/api/camera_proxy/<camera entity_id>
🔒
get
/api/calendars
🔒
get
/api/calendars/<calendar entity_id>
🔒
post
/api/states/<entity_id>
🔒
post
/api/events/<event_type>
🔒
post
/api/services/<domain>/<service>
🔒
post
/api/template
🔒
post
/api/config/core/check_config
🔒
post
/api/intent/handle
🔒
Edit this page
Last updated on Nov 29, 2023
Previous
WebSocket API
Next
Validate the input
 * Actions

More Home Assistant
 * Homepage
 * Data Science Portal
 * Alerts
 * System Status

Social
 * Blog
 * GitHub
 * Twitter
 * Discord chat

Other
 * Privacy
 * Security

Thanks
 * 

Copyright © 2024 Home Assistant. Built with Docusaurus.