home-assistant.io/rest_api.markdown at 5db92238a5e453485d087f45d670d9a86557bcd4

jeans/home-assistant.io

Fork 0

mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-05-04 01:58:57 +00:00

Fabian Affolter 258d4172d8 Add content-type to curl (#531 )

2016-06-04 17:38:33 +02:00

12 KiB

Raw Blame History

layout, title, description, date, sidebar, comments, sharing, footer

layout	title	description	date	sidebar	comments	sharing	footer
page	RESTful API	Home Assistant RESTful API documentation	2014-12-21 13:27	true	false	true	true

Home Assistant runs a web server accessible on port 8123.

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

The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header X-HA-Access: YOUR_PASSWORD (YOUR_PASSWORD as specified in your configuration.yaml file in the http: section).

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

curl -X GET \
    -H "x-ha-access: YOUR_PASSWORD" \
    -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 = {'x-ha-access': 'YOUR_PASSWORD',
           'content-type': 'application/json'}

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

You can append ?api_password=YOUR_PASSWORD to any url to log in automatically.

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)

{% linkable_title Actions %}

The API supports the following actions:

{% linkable_title GET /api/ %}

Returns message if API is up and running.

{
  "message": "API running."
}

Sample curl command:

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" http://localhost:8123/api/

{% linkable_title GET /api/config %}

Returns the current configuration as JSON.

{
    "components": [
        "recorder",
        "http",
        "sensor.time_date",
        "api",
        "frontend",
        "sun",
        "logbook",
        "history",
        "group",
        "automation"
    ],
    "latitude": 44.1234,
    "location_name": "Home",
    "longitude": 5.5678,
    "temperature_unit": "\u00b0C",
    "time_zone": "Europe/Zurich",
    "version": "0.8.0.dev0"
}

Sample curl command:

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" http://localhost:8123/api/config

{% linkable_title GET /api/discovery_info %}

Returns basic information about the Home Assistant instance as JSON.

{
    "base_url": "http://127.0.0.1:8123",
    "location_name": "Home",
    "requires_api_password": true,
    "version": "0.20.0.dev0"
}

Sample curl command:

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" http://localhost:8123/api/discovery_info

{% linkable_title GET /api/bootstrap %}

Returns all data needed to bootstrap Home Assistant.

{
    "config": {...},
    "events": [...],
    "services": [...],
    "states": [...]
}

Sample curl command:

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" http://localhost:8123/api/bootstrap

{% linkable_title GET /api/events %}

Returns an array of event objects. Each event object contain event name and listener count.

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

Sample curl command:

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" http://localhost:8123/api/events

{% linkable_title GET /api/services %}

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

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

Sample curl command:

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" http://localhost:8123/api/services

{% linkable_title GET /api/history %}

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

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

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       http://localhost:8123/api/history/period/2016-02-06

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       http://localhost:8123/api/history/period/2016-02-06?filter_entity_id=sensor.temperature

{% linkable_title GET /api/states %}

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

[
    {
        "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"
    }
]

Sample curl command:

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" http://localhost:8123/api/states

{% linkable_title GET /api/states/<entity_id> %}

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

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

Sample curl command:

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       http://localhost:8123/api/states/sensor.kitchen_temperature

{% linkable_title GET /api/error_log %}

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

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

Sample curl command:

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       http://localhost:8123/api/error_log

{% linkable_title GET /api/camera_proxy/camera.<entity_id> %}

Returns the data (image) from the specified camera entity_id.

Sample curl command:

$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time=1462653861261 -o image.jpg

{% linkable_title POST /api/states/<entity_id> %}

Updates or creates the current state of an entity.

Expects a JSON object that has at least a state attribute:

{
    "state": "below_horizon",
    "attributes": {
        "next_rising":"2016-05-31T03:39:14+00:00",
        "next_setting":"2016-05-31T19:16:42+00:00"
    }
}

Return code is 200 if the entity existed, 201 if the state of a new entity was set. A location header will be returned with the url of the new resource. The response body will contain a JSON encoded State object.

{
    "attributes": {
        "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:47:30.533530+00:00"
    "state": "below_horizon"
}

Sample curl command:

$ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       -d '{"state": "25", "attributes": {"unit_of_measurement": "°C"}}' \
       http://localhost:8123/api/states/sensor.kitchen_temperature

{% linkable_title POST /api/events/<event_type> %}

Fires an event with event_type

You can pass an optional JSON object to be used as event_data.

{
    next_rising":"2016-05-31T03:39:14+00:00",
}

Returns a message if successful.

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

{% linkable_title POST /api/services/<domain>/<service> %}

Calls a service within a specific domain. Will return when the service has been executed or 10 seconds has past, whichever comes first.

You can pass an optional JSON object to be used as service_data.

{
    "entity_id": "light.Ceiling"
}

Returns a list of states that have changed while the service was being executed.

[
    {
        "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"
    }
]

Sample curl command:

$ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       -d '{"entity_id": "switch.christmas_lights", "state": "on"}' \
       http://localhost:8123/api/services/switch/turn_on

The result will include any changed states that changed while the service was being executed, even if their change was the result of something else happening in the system.

{% linkable_title POST /api/template %}

Render a Home Assistant template. See template docs for more information.

{
    "template": "Paulus is at {% raw %}{{ states('device_tracker.paulus') }}{% endraw %}!"
}

Returns the rendered template in plain text.

Paulus is at work!

Sample curl command:

$ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
       -H "Content-Type: application/json" \
       -d '{"template": "It is {{ now }}!"}' http://localhost:8123/api/template

{% linkable_title POST /api/event_forwarding %}

Setup event forwarding to another Home Assistant instance.

Requires a JSON object that represents the API to forward to.

{
    "host": "machine",
    "api_password": "my_super_secret_password",
    "port": 8880 // optional
}

It will return a message if event forwarding was setup successful.

{
    "message": "Event forwarding setup."
}

{% linkable_title DELETE /api/event_forwarding %}

Cancel event forwarding to another Home Assistant instance.

Requires a JSON object that represents the API to cancel forwarding to.

{
    "host": "machine",
    "api_password": "my_super_secret_password",
    "port": 8880 // optional
}

It will return a message if event forwarding was cancelled successful.

{
    "message": "Event forwarding cancelled."
}

If your client does not support DELETE HTTP requests you can add an optional attribute _METHOD and set its value to DELETE.

12 KiB Raw Blame History

{% linkable_title Actions %}

{% linkable_title GET /api/ %}

{% linkable_title GET /api/config %}

{% linkable_title GET /api/discovery_info %}

{% linkable_title GET /api/bootstrap %}

{% linkable_title GET /api/events %}

{% linkable_title GET /api/services %}

{% linkable_title GET /api/history %}

{% linkable_title GET /api/states %}

{% linkable_title GET /api/states/<entity_id> %}

{% linkable_title GET /api/error_log %}

{% linkable_title GET /api/camera_proxy/camera.<entity_id> %}

{% linkable_title POST /api/states/<entity_id> %}

{% linkable_title POST /api/events/<event_type> %}

{% linkable_title POST /api/services/<domain>/<service> %}

{% linkable_title POST /api/template %}

{% linkable_title POST /api/event_forwarding %}

{% linkable_title DELETE /api/event_forwarding %}

12 KiB

Raw Blame History