Welcome to Homeassistant API!

Homeassistant API is a pythonic module that interacts with Homeassistant’s REST API integration and Homeassistant’s Websocket API. You can use it to remotely control your Home Assistant to do things like turn on lights, change the temperature, or listen for when the garage door opens.

Index

• Home
• Quickstart
• Usage
• Code Reference
• Contributing
• Advanced

Features

1. Full consumption of the Home Assistant REST API endpoints.

2. Full consumption of the Home Assistant Websocket API (all of the documented commands and some undocumented ones).

3. Convenient Pydantic Models for data validation.

4. Synchronous and asynchronous support for both REST and WebSocket clients.

5. Modular design for intuitive readability.

6. Request caching for more efficient repetitive requests.

Getting Started

Is this your first time using the library? Start with our Quickstart Section

Example

import os

from homeassistant_api import Client

api_url = "http://localhost:8123/api"  # Something like http://<host>:8123/api, the /api is important!
token = os.getenv(
    "HOMEASSISTANT_TOKEN",  # Used to aunthenticate yourself with homeassistant
)
# See the documentation on how to obtain a Long Lived Access Token


def main() -> None:
    # Create Client object and check that its running.
    with Client(api_url, token) as client:
        cover = client.get_domain("cover")
        if cover is None:
            return

        # Tells Home Assistant to trigger the toggle service on the given entity_id
        cover.toggle(entity_id="cover.garage_door")


if __name__ == "__main__":
    main()

Want to look at more? Many more examples are available in the repository. We encourage you to open a pull request and add your own after you get to know the library! See the Contributing Section.

More Usage

View the documentation for each class and method here.

Contributing Guidelines

We absolutely love contributions! This library has come a long way since its one-file humble beginning on a Saturday afternoon. However, while much has been done already there is still much much much more to do, which is as exciting as it daunting! If you’re a developer that has an idea/suggestion or just wants to be helpful, see our Development and Contribution page for contribution ideas to get started, guidance, and what to expect with your PR. Happy developing, and we hope to see your PRs soon.