API

self.api sends commands to Home Assistant and retrieves data from it. It wraps the REST and WebSocket APIs with automatic authentication, retries, and type conversion. Every App instance has one.

Quick Example

The two most common operations are reading state and calling a service.

from hassette import App
from hassette.exceptions import HassetteError


class SunApp(App):
    async def on_initialize(self):
        try:
            state = await self.api.get_state("sun.sun")
            self.logger.info("Sun is %s", state.value)
        except HassetteError as e:
            self.logger.error("HA API error: %s", e)

get_state() fetches the entity from Home Assistant over the network. It returns a typed state object with .value (the state string) and .attributes (domain-specific fields). call_service() sends a service call via WebSocket.

API vs StateManager

self.states covers most state-reading needs. It returns typed state objects from a local cache, with no network call and no await.

	self.states	self.api
Access pattern	Synchronous	async / await
Data source	Local cache, updated from HA events	Direct from Home Assistant
Latency	Instant	Network round-trip
Best for	Reading state in handlers	Writes, fresh data, helpers

self.states is faster and simpler for reads. self.api is the right choice when fresh-from-HA data is needed, or for any write operation: service calls, set_state(), and managing HA helpers (input_boolean, counter, timer, etc.).

Error Handling

Api raises typed exceptions for common failures.

• EntityNotFoundError if the entity does not exist in Home Assistant.
• InvalidAuthError if authentication failed (invalid or expired token).
• HassetteError for any other upstream error from Home Assistant.

Network errors are retried automatically. Catching HassetteError handles all API failures in one place.

Synchronous usage (AppSync only)

self.api.sync exposes an ApiSyncFacade that mirrors all API methods as blocking calls. It exists for AppSync lifecycle hooks, which run outside the async event loop. The Apps page covers the AppSync pattern.

Next Steps

• API Methods: all self.api methods organized by task: reading state, calling services, history, templates, and more.
• Managing Helpers: creating and managing input helpers (booleans, counters, timers, and more).