home-assistant.io/source/developers/api.markdown

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

layout	title	date	sidebar	comments	sharing	footer
page	Rest API	2014-12-21 13:27	false	true	true	true

Home Assistent runs a webserver accessible on port 8123.

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

In the package homeassistant.remote a Python API on top of the HTTP API can be found.

The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header X-HA-Access: YOUR_PASSWORD (as specified in your home-assistant.conf).

Note

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)

The api supports the following actions:

GET /api

Returns message if API is up and running.

{
  "message": "API running."
}

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
    }
]

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

GET /api/states

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

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

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

{
    "state": "below_horizon",
    "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.

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

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

Returns a message if successful.

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

{
    "entity_id": "light.Ceiling"
}

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

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

Note

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.

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

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

Note

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