Home Assistant

Rest API

Home Assistant runs a web server accessible on port 8123.

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).

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

1
2
3

curl -X GET \
    -H "x-ha-access: YOUR_PASSWORD" \
    http://localhost:8123/api

Another option is to use Python and the Requests module.

1
2
3
4
5
6
7
8

from requests import get

url = 'http://localhost:8123/api/'
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)

Actions

The API supports the following actions:

GET /api

Returns message if API is up and running.

1
2
3

{
  "message": "API running."
}

GET /api/events

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

1
2
3
4
5
6
7
8
9
10

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

GET /api/services

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

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

GET /api/states

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

[
    {
        "attributes": {
            "next_rising": "07:04:15 29-10-2013",
            "next_setting": "18:00:31 29-10-2013"
        },
        "entity_id": "sun.sun",
        "last_changed": "23:24:33 28-10-2013",
        "state": "below_horizon"
    },
    {
        "attributes": {},
        "entity_id": "process.Dropbox",
        "last_changed": "23:24:33 28-10-2013",
        "state": "on"
    }
]

GET /api/states/<entity_id>

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

1
2
3
4
5
6
7
8
9

{
    "attributes": {
        "next_rising": "07:04:15 29-10-2013",
        "next_setting": "18:00:31 29-10-2013"
    },
    "entity_id": "sun.sun",
    "last_changed": "23:24:33 28-10-2013",
    "state": "below_horizon"
}

POST /api/states/<entity_id>

Updates or creates the current state of an entity.

Expects a JSON object that has atleast a state attribute:

1
2
3
4
5
6
7

{
    "state": "below_horizon",
    "attributes": {
        "next_rising": "07:04:15 29-10-2013",
        "next_setting": "18:00:31 29-10-2013"
    }
}

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.

1
2
3
4
5
6
7
8
9

{
    "attributes": {
        "next_rising": "07:04:15 29-10-2013",
        "next_setting": "18:00:31 29-10-2013"
    },
    "entity_id": "weather.sun",
    "last_changed": "23:24:33 28-10-2013",
    "state": "below_horizon"
}

POST /api/events/<event_type>

Fires an event with event_type

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

1
2
3

{
    "next_rising": "18:00:31 29-10-2013"
}

Returns a message if successful.

1
2
3

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

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.

1
2
3

{
    "entity_id": "light.Ceiling"
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

[
    {
        "attributes": {
            "next_rising": "07:04:15 29-10-2013",
            "next_setting": "18:00:31 29-10-2013"
        },
        "entity_id": "sun.sun",
        "last_changed": "23:24:33 28-10-2013",
        "state": "below_horizon"
    },
    {
        "attributes": {},
        "entity_id": "process.Dropbox",
        "last_changed": "23:24:33 28-10-2013",
        "state": "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.

POST /api/event_forwarding

Setup event forwarding to another Home Assistant instance.

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

1
2
3
4
5

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

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

1
2
3

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

DELETE /api/event_forwarding

Cancel event forwarding to another Home Assistant instance.

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

1
2
3
4
5

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

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

1
2
3

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