Index

API functionality for interacting with Home Assistant.

This module provides clean access to the API classes for making HTTP requests, managing WebSocket connections, and handling entity states.

Api

Bases: Resource

API service for interacting with Home Assistant.

This service provides methods to interact with the Home Assistant API, including making REST requests, managing WebSocket connections, and handling entity states.

Source code in src/hassette/api/api.py

class Api(Resource):
    """API service for interacting with Home Assistant.

    This service provides methods to interact with the Home Assistant API, including making REST requests,
    managing WebSocket connections, and handling entity states.
    """

    sync: ApiSyncFacade
    """Synchronous facade for the API service."""

    _api_service: "ApiResource"
    """Internal API service instance."""

    def __init__(self, hassette: "Hassette", *, parent: Resource | None = None) -> None:
        super().__init__(hassette, parent=parent)
        assert self.hassette._api_service is not None
        self._api_service = self.hassette._api_service
        self.sync = self.add_child(ApiSyncFacade, api=self)

    async def on_initialize(self) -> None:
        self.mark_ready(reason="API initialized")

    @property
    def config_log_level(self) -> LOG_LEVEL_TYPE:
        """Return the log level from the config for this resource."""
        return self.hassette.config.logging.api

    async def ws_send_and_wait(self, **data: Any) -> Any:
        """Send a WebSocket message and wait for a response."""
        return await self._api_service._ws_conn.send_and_wait(**data)

    async def ws_send_json(self, **data: Any) -> None:
        """Send a WebSocket message without waiting for a response."""
        await self._api_service._ws_conn.send_json(**data)

    async def rest_request(
        self,
        method: str,
        url: str,
        params: dict[str, Any] | None = None,
        data: dict[str, Any] | None = None,
        suppress_error_message: bool = False,
        **kwargs: Any,
    ) -> aiohttp.ClientResponse:
        """Make a REST request to the Home Assistant API.

        Args:
            method: The HTTP method to use (e.g., "GET", "POST").
            url: The URL endpoint for the request.
            params: Query parameters for the request.
            data: JSON payload for the request.
            suppress_error_message: Whether to suppress error messages.

        Returns:
            The response from the API.
        """
        return await self._api_service._rest_request(
            method, url, params=params, data=data, suppress_error_message=suppress_error_message, **kwargs
        )

    async def get_rest_request(
        self, url: str, params: dict[str, Any] | None = None, **kwargs: Any
    ) -> aiohttp.ClientResponse:
        """Make a GET request to the Home Assistant API.

        Args:
            url: The URL endpoint for the request.
            params: Query parameters for the request.
            kwargs: Additional keyword arguments to pass to the request.

        Returns:
            The response from the API.
        """
        return await self.rest_request("GET", url, params=params, **kwargs)

    async def post_rest_request(
        self, url: str, data: dict[str, Any] | None = None, **kwargs: Any
    ) -> aiohttp.ClientResponse:
        """Make a POST request to the Home Assistant API.

        Args:
            url: The URL endpoint for the request.
            data: JSON payload for the request.
            kwargs: Additional keyword arguments to pass to the request.

        Returns:
            The response from the API.
        """
        return await self.rest_request("POST", url, data=data, **kwargs)

    async def delete_rest_request(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
        """Make a DELETE request to the Home Assistant API.

        Args:
            url: The URL endpoint for the request.
            kwargs: Additional keyword arguments to pass to the request.

        Returns:
            The response from the API.
        """
        return await self.rest_request("DELETE", url, **kwargs)

    async def get_states_raw(self) -> list["HassStateDict"]:
        """Get all entities in Home Assistant as raw dictionaries.

        Returns:
            A list of states as dictionaries.
        """
        val = await self.ws_send_and_wait(type="get_states")
        return _expect_list(val, "get_states")

    async def get_states(self) -> list["BaseState"]:
        """Get all entities in Home Assistant, converted to their appropriate state types.

        If a state fails to convert, it is skipped with an error logged. If there is no registered
        state class for a domain, the generic BaseState is used.

        Returns:
            A list of states, converted to their appropriate state types.
        """
        val = await self.get_states_raw()

        self.logger.debug("Converting states to specific state types")
        converted: list[BaseState] = []

        for raw_state in val:
            # the conversion method will handle logging any conversion errors
            with suppress(UnableToConvertStateError):
                state = self.hassette.state_registry.try_convert_state(raw_state)
                converted.append(state)

        return converted

    async def get_config(self) -> dict[str, Any]:
        """Get the Home Assistant configuration.

        Returns:
            The configuration data.
        """
        val = await self.ws_send_and_wait(type="get_config")
        return _expect_dict(val, "get_config")

    async def get_services(self) -> dict[str, Any]:
        """Get the available services in Home Assistant.

        Returns:
            The services data.
        """
        val = await self.ws_send_and_wait(type="get_services")
        return _expect_dict(val, "get_services")

    async def get_panels(self) -> dict[str, Any]:
        """Get the available panels in Home Assistant.

        Returns:
            The panels data.
        """
        val = await self.ws_send_and_wait(type="get_panels")
        return _expect_dict(val, "get_panels")

    async def fire_event(
        self,
        event_type: str,
        event_data: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Fire a custom event in Home Assistant.

        Args:
            event_type: The type of the event to fire (e.g., "custom_event").
            event_data: Additional data to include with the event.

        Returns:
            The response from Home Assistant.
        """
        event_data = event_data or {}

        data = {"type": "fire_event", "event_type": event_type, "event_data": event_data}
        if not event_data:
            data.pop("event_data")

        return await self.ws_send_and_wait(**data)

    @overload
    async def call_service(
        self,
        domain: str,
        service: str,
        target: dict[str, str] | dict[str, list[str]] | None,
        return_response: Literal[True],
        **data: Any,
    ) -> ServiceResponse: ...

    @overload
    async def call_service(
        self,
        domain: str,
        service: str,
        target: dict[str, str] | dict[str, list[str]] | None = None,
        return_response: typing.Literal[False] | None = None,
        **data: Any,
    ) -> None: ...

    async def call_service(
        self,
        domain: str,
        service: str,
        target: dict[str, str] | dict[str, list[str]] | None = None,
        return_response: bool | None = False,
        **data: Any,
    ) -> ServiceResponse | None:
        """Call a Home Assistant service.

        Args:
            domain: The domain of the service (e.g., "light").
            service: The name of the service to call (e.g., "turn_on").
            target: Target entity IDs or areas.
            return_response: Whether to return the response from Home Assistant. Defaults to False.
            **data: Additional data to send with the service call.

        Returns:
            ServiceResponse | None: The response from Home Assistant if return_response is True. Otherwise None.
        """
        payload = {
            "type": "call_service",
            "domain": domain,
            "service": service,
            "target": target,
            "return_response": return_response,
        }

        payload = {k: v for k, v in payload.items() if v is not None}
        data = {k: v for k, v in data.items() if v is not None}

        if data:
            self.logger.debug("Adding extra data to service call: %s", data)
            payload["service_data"] = data

        if return_response:
            resp = await self.ws_send_and_wait(**payload)
            return ServiceResponse(**resp)

        await self.ws_send_json(**payload)
        return None

    async def turn_on(self, entity_id: str | StrEnum, domain: str = "homeassistant", **data: Any) -> None:
        """Turn on a specific entity in Home Assistant.

        Args:
            entity_id: The ID of the entity to turn on (e.g., "light.office").
            domain: The domain to use for the service call (default: ``"homeassistant"``).
                This calls the generic ``homeassistant.turn_on`` service, which is deprecated
                in Home Assistant 2024.x in favor of domain-specific services. For lights,
                pass ``domain="light"``; for switches, pass ``domain="switch"``.

        """
        entity_id = str(entity_id)

        self.logger.debug("Turning on entity %s", entity_id)
        return await self.call_service(domain=domain, service="turn_on", target={"entity_id": entity_id}, **data)

    async def turn_off(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
        """Turn off a specific entity in Home Assistant.

        Args:
            entity_id: The ID of the entity to turn off (e.g., "light.office").
            domain: The domain to use for the service call (default: ``"homeassistant"``).
                This calls the generic ``homeassistant.turn_off`` service, which is deprecated
                in Home Assistant 2024.x in favor of domain-specific services. For lights,
                pass ``domain="light"``; for switches, pass ``domain="switch"``.

        """
        entity_id = str(entity_id)
        self.logger.debug("Turning off entity %s", entity_id)
        return await self.call_service(domain=domain, service="turn_off", target={"entity_id": entity_id})

    async def toggle_service(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
        """Toggle a specific entity in Home Assistant.

        Args:
            entity_id: The ID of the entity to toggle (e.g., "light.office").
            domain: The domain to use for the service call (default: ``"homeassistant"``).
                This calls the generic ``homeassistant.toggle`` service, which is deprecated
                in Home Assistant 2024.x in favor of domain-specific services. For lights,
                pass ``domain="light"``; for switches, pass ``domain="switch"``.

        """
        entity_id = str(entity_id)
        self.logger.debug("Toggling entity %s", entity_id)
        return await self.call_service(domain=domain, service="toggle", target={"entity_id": entity_id})

    async def get_state_raw(self, entity_id: str) -> "HassStateDict":
        """Get the state of a specific entity.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity as raw data.
        """

        url = f"states/{entity_id}"
        response = await self.get_rest_request(url)
        return await response.json()

    async def entity_exists(self, entity_id: str) -> bool:
        """Check if a specific entity exists.

        Args:
            entity_id: The ID of the entity to check.

        Returns:
            True if the entity exists, False otherwise.
        """

        try:
            url = f"states/{entity_id}"
            response = await self.rest_request("GET", url, suppress_error_message=True)
            await response.json()
            return True
        except EntityNotFoundError:
            return False

    async def get_entity(self, entity_id: str, model: type["EntityT"]) -> "EntityT":
        """Get an entity object for a specific entity.

        Args:
            entity_id: The ID of the entity to get.
            model: The model class to use for the entity.

        Returns:
            The entity object.
        """
        if not issubclass(model, BaseEntity):  # runtime check
            raise TypeError(f"Model {model!r} is not a valid BaseEntity subclass")

        raw = await self.get_state_raw(entity_id)

        return model.model_validate({"state": raw})

    async def get_entity_or_none(self, entity_id: str, model: type["EntityT"]) -> "EntityT | None":
        """Get an entity object for a specific entity, or None if it does not exist.

        Args:
            entity_id: The ID of the entity to get.
            model: The model class to use for the entity.

        Returns:
            The entity object, or None if it does not exist.
        """
        try:
            return await self.get_entity(entity_id, model)
        except aiohttp.ClientResponseError as e:
            if e.status == 404:
                return None
            raise

    async def get_state(self, entity_id: str) -> "BaseState":
        """Get the state of a specific entity.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity converted to the specified model type.
        """

        raw = await self.get_state_raw(entity_id)
        return self.hassette.state_registry.try_convert_state(raw, entity_id)

    async def get_state_or_none(self, entity_id: str) -> "BaseState | None":
        """Get the state of a specific entity, or None if it does not exist.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity converted to the specified model type, or None if it does not exist.
        """
        try:
            return await self.get_state(entity_id)
        except aiohttp.ClientResponseError as e:
            if e.status == 404:
                return None
            raise

    async def get_state_value(self, entity_id: str) -> Any:
        """Get the state of a specific entity without converting it to a state object.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity as raw data.

        Note:
            While most default methods in this library work with state objects for
            strong typing, this method is designed to return the raw state value,
            as it is likely overkill to convert it to a state object for simple state value retrieval.
        """

        entity = await self.get_state_raw(entity_id)
        state = entity.get("state")
        return state

    async def get_state_value_typed(self, entity_id: str) -> "Any":
        """Get the value of a specific entity's state, converted to the correct type for that state.

        The return type here is Any due to the dynamic nature of this conversion, but the return type
        at runtime will match the expected value type for the specific state class of the entity.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity converted to the specified model type.

        Raises:
            TypeError: If the model is not a valid StateType subclass.

        Warning:
            For states like `SensorState` the value type in Hassette is `str`, even if the sensor represents a number,
            as we cannot be sure of the actual type without additional context. For these cases, you are responsible
            for converting the string to the desired type.
        """
        state_raw = await self.get_state_raw(entity_id)
        state = state_raw.get("state")

        model = self.hassette.state_registry.resolve(domain=entity_id.split(".")[0])
        if not model:
            return state
        return self.hassette.type_registry.convert(state, model.value_type)

    async def get_attribute(self, entity_id: str, attribute: str) -> Any | FalseySentinel:
        """Get a specific attribute of an entity.

        Args:
            entity_id: The ID of the entity to get the attribute for.
            attribute: The name of the attribute to retrieve. Can be a dot-separated path for nested attributes.

        Returns:
            The value of the specified attribute, or MISSING_VALUE sentinel if the attribute does not exist.
        """

        entity = await self.get_state(entity_id)
        return get_path(attribute)(entity.attributes)

    async def get_history(
        self,
        entity_id: str,
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
        significant_changes_only: bool = False,
        minimal_response: bool = False,
        no_attributes: bool = False,
    ) -> list[HistoryEntry]:
        """Get the history of a specific entity.

        Args:
            entity_id: The ID of the entity to get the history for.
            start_time: The start time for the history range.
            end_time: The end time for the history range.
            significant_changes_only: Whether to only include significant changes.
            minimal_response: Whether to request a minimal response.
            no_attributes: Whether to exclude attributes from the response.

        Returns:
            A list of history entries for the specified entity.
        """
        if "," in entity_id:
            raise ValueError("Entity ID should not contain commas. Use `get_histories` for multiple entities.")

        entries = await self._api_service._get_history_raw(
            entity_id=entity_id,
            start_time=start_time,
            end_time=end_time,
            significant_changes_only=significant_changes_only,
            minimal_response=minimal_response,
            no_attributes=no_attributes,
        )

        if not entries:
            return []

        assert len(entries) == 1, "Expected a single list of history entries"

        converted = [HistoryEntry.model_validate(entry) for entry in entries[0]]

        return converted

    async def get_histories(
        self,
        entity_ids: list[str],
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
        significant_changes_only: bool = False,
        minimal_response: bool = False,
        no_attributes: bool = False,
    ) -> dict[str, list[HistoryEntry]]:
        """Get the history for multiple entities.

        Args:
            entity_ids: The IDs of the entities to get the history for.
            start_time: The start time for the history range.
            end_time: The end time for the history range.
            significant_changes_only: Whether to only include significant changes.
            minimal_response: Whether to request a minimal response.
            no_attributes: Whether to exclude attributes from the response.

        Returns:
            A dictionary mapping entity IDs to their respective history entries.
        """
        entity_id = ",".join(entity_ids)

        entries = await self._api_service._get_history_raw(
            entity_id=entity_id,
            start_time=start_time,
            end_time=end_time,
            significant_changes_only=significant_changes_only,
            minimal_response=minimal_response,
            no_attributes=no_attributes,
        )

        if not entries:
            return {}

        converted = {}
        for history_list in entries:
            converted[history_list[0]["entity_id"]] = [HistoryEntry.model_validate(entry) for entry in history_list]

        return converted

    async def get_logbook(
        self,
        entity_id: str,
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str,
    ) -> list[dict]:
        """Get the logbook entries for a specific entity.

        Args:
            entity_id: The ID of the entity to get the logbook entries for.
            start_time: The start time for the logbook range.
            end_time: The end time for the logbook range.

        Returns:
            A list of logbook entries for the specified entity.
        """

        url = f"logbook/{format_time_param(start_time)}"
        params = {"entity": entity_id, "end_time": end_time}

        response = await self.get_rest_request(url, params=params)

        return await response.json()

    async def set_state(
        self,
        entity_id: str | StrEnum,
        state: Any,
        attributes: dict[str, Any] | None = None,
    ) -> dict:
        """Set the state of a specific entity.

        Args:
            entity_id: The ID of the entity to set the state for.
            state: The new state value to set.
            attributes: Additional attributes to set for the entity.

        Returns:
            The response from Home Assistant after setting the state.
        """

        entity_id = str(entity_id)

        attributes = attributes or {}
        curr_attributes = {}

        if await self.entity_exists(entity_id):
            curr_attributes = (await self.get_state_raw(entity_id)).get("attributes", {}) or {}

        # Merge current attributes with new attributes
        new_attributes = curr_attributes | attributes

        url = f"states/{entity_id}"
        data = {"state": state, "attributes": new_attributes}

        response = await self.post_rest_request(url, data=data)
        return await response.json()

    async def get_camera_image(
        self,
        entity_id: str,
        timestamp: PlainDateTime | ZonedDateTime | Date | str | None = None,
    ) -> bytes:
        """Get the latest camera image for a specific entity.

        Args:
            entity_id: The ID of the camera entity to get the image for.
            timestamp: The timestamp for the image. If None, the latest image is returned.

        Returns:
            The camera image data.
        """

        url = f"camera_proxy/{entity_id}"
        params = {}
        if timestamp:
            params["timestamp"] = timestamp

        response = await self.get_rest_request(url, params=params)

        return await response.read()

    async def get_calendars(self) -> list[dict]:
        """Get the list of calendars."""

        url = "calendars"
        response = await self.get_rest_request(url)
        return await response.json()

    async def get_calendar_events(
        self,
        calendar_id: str,
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str,
    ) -> list[dict]:
        """Get events from a specific calendar.

        Args:
            calendar_id: The ID of the calendar to get events from.
            start_time: The start time for the event range.
            end_time: The end time for the event range.

        Returns:
            A list of calendar events.
        """

        url = f"calendars/{calendar_id}/events"
        params = {"start": start_time, "end": end_time}

        response = await self.get_rest_request(url, params=params)
        return await response.json()

    async def render_template(
        self,
        template: str,
        variables: dict | None = None,
    ) -> str:
        """Render a template with given variables.

        Args:
            template: The template string to render.
            variables: Variables to use in the template.

        Returns:
            The rendered template result.
        """

        url = "template"
        data = {"template": template, "variables": variables or {}}

        response = await self.post_rest_request(url, data=data)
        return await response.text()

    async def delete_entity(self, entity_id: str) -> None:
        """Delete a specific entity.

        Args:
            entity_id: The ID of the entity to delete.

        Raises:
            RuntimeError: If the deletion fails.
        """

        url = f"states/{entity_id}"

        response = await self.rest_request("DELETE", url)

        if response.status != 204:
            raise RuntimeError(f"Failed to delete entity {entity_id}: {response.status} - {response.reason}")

    # All 32 methods use _ws_helper_call for consistent error context.
    # Command pattern: {domain}/{list|create|update|delete}
    # ID key pattern:  {domain}_id  (uniform across all 8 domains — see design.md
    #                  § HA WebSocket Commands / Shared infrastructure)

    async def list_input_booleans(self) -> list[InputBooleanRecord]:
        """List all stored input_boolean helpers.

        Returns:
            List of InputBooleanRecord instances representing stored configs.
        """
        val = await _ws_helper_call(self, "input_boolean", "list")
        items = _expect_list(val, "input_boolean/list")
        self.logger.debug("Listed %d input_boolean helpers", len(items))
        return [InputBooleanRecord.model_validate(item) for item in items]

    async def create_input_boolean(self, params: CreateInputBooleanParams) -> InputBooleanRecord:
        """Create a new input_boolean helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant.
        """
        val = await _ws_helper_call(self, "input_boolean", "create", **params.model_dump(exclude_unset=True))
        record = InputBooleanRecord.model_validate(_expect_dict(val, "input_boolean/create"))
        self.logger.info("Created input_boolean helper %r", record.id)
        return record

    async def update_input_boolean(self, helper_id: str, params: UpdateInputBooleanParams) -> InputBooleanRecord:
        """Update an existing input_boolean helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record.
        """
        val = await _ws_helper_call(
            self,
            "input_boolean",
            "update",
            input_boolean_id=helper_id,
            **params.model_dump(exclude_unset=True),
        )
        record = InputBooleanRecord.model_validate(_expect_dict(val, "input_boolean/update"))
        self.logger.debug("Updated input_boolean helper %r", helper_id)
        return record

    async def delete_input_boolean(self, helper_id: str) -> None:
        """Delete an input_boolean helper.

        Args:
            helper_id: The ID of the helper to delete.
        """
        await _ws_helper_call(self, "input_boolean", "delete", input_boolean_id=helper_id)
        self.logger.debug("Deleted input_boolean helper %r", helper_id)

    async def list_input_numbers(self) -> list[InputNumberRecord]:
        """List all stored input_number helpers.

        Returns:
            List of InputNumberRecord instances representing stored configs.
        """
        val = await _ws_helper_call(self, "input_number", "list")
        items = _expect_list(val, "input_number/list")
        self.logger.debug("Listed %d input_number helpers", len(items))
        return [InputNumberRecord.model_validate(item) for item in items]

    async def create_input_number(self, params: CreateInputNumberParams) -> InputNumberRecord:
        """Create a new input_number helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant.
        """
        val = await _ws_helper_call(self, "input_number", "create", **params.model_dump(exclude_unset=True))
        record = InputNumberRecord.model_validate(_expect_dict(val, "input_number/create"))
        self.logger.info("Created input_number helper %r", record.id)
        return record

    async def update_input_number(self, helper_id: str, params: UpdateInputNumberParams) -> InputNumberRecord:
        """Update an existing input_number helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record.
        """
        val = await _ws_helper_call(
            self,
            "input_number",
            "update",
            input_number_id=helper_id,
            **params.model_dump(exclude_unset=True),
        )
        record = InputNumberRecord.model_validate(_expect_dict(val, "input_number/update"))
        self.logger.debug("Updated input_number helper %r", helper_id)
        return record

    async def delete_input_number(self, helper_id: str) -> None:
        """Delete an input_number helper.

        Args:
            helper_id: The ID of the helper to delete.
        """
        await _ws_helper_call(self, "input_number", "delete", input_number_id=helper_id)
        self.logger.debug("Deleted input_number helper %r", helper_id)

    async def list_input_texts(self) -> list[InputTextRecord]:
        """List all stored input_text helpers.

        Returns:
            List of InputTextRecord instances representing stored configs.
        """
        val = await _ws_helper_call(self, "input_text", "list")
        items = _expect_list(val, "input_text/list")
        self.logger.debug("Listed %d input_text helpers", len(items))
        return [InputTextRecord.model_validate(item) for item in items]

    async def create_input_text(self, params: CreateInputTextParams) -> InputTextRecord:
        """Create a new input_text helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant.
        """
        val = await _ws_helper_call(self, "input_text", "create", **params.model_dump(exclude_unset=True))
        record = InputTextRecord.model_validate(_expect_dict(val, "input_text/create"))
        self.logger.info("Created input_text helper %r", record.id)
        return record

    async def update_input_text(self, helper_id: str, params: UpdateInputTextParams) -> InputTextRecord:
        """Update an existing input_text helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record.
        """
        val = await _ws_helper_call(
            self,
            "input_text",
            "update",
            input_text_id=helper_id,
            **params.model_dump(exclude_unset=True),
        )
        record = InputTextRecord.model_validate(_expect_dict(val, "input_text/update"))
        self.logger.debug("Updated input_text helper %r", helper_id)
        return record

    async def delete_input_text(self, helper_id: str) -> None:
        """Delete an input_text helper.

        Args:
            helper_id: The ID of the helper to delete.
        """
        await _ws_helper_call(self, "input_text", "delete", input_text_id=helper_id)
        self.logger.debug("Deleted input_text helper %r", helper_id)

    async def list_input_selects(self) -> list[InputSelectRecord]:
        """List all stored input_select helpers.

        Returns:
            List of InputSelectRecord instances representing stored configs.
        """
        val = await _ws_helper_call(self, "input_select", "list")
        items = _expect_list(val, "input_select/list")
        self.logger.debug("Listed %d input_select helpers", len(items))
        return [InputSelectRecord.model_validate(item) for item in items]

    async def create_input_select(self, params: CreateInputSelectParams) -> InputSelectRecord:
        """Create a new input_select helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant.
        """
        val = await _ws_helper_call(self, "input_select", "create", **params.model_dump(exclude_unset=True))
        record = InputSelectRecord.model_validate(_expect_dict(val, "input_select/create"))
        self.logger.info("Created input_select helper %r", record.id)
        return record

    async def update_input_select(self, helper_id: str, params: UpdateInputSelectParams) -> InputSelectRecord:
        """Update an existing input_select helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record.
        """
        val = await _ws_helper_call(
            self,
            "input_select",
            "update",
            input_select_id=helper_id,
            **params.model_dump(exclude_unset=True),
        )
        record = InputSelectRecord.model_validate(_expect_dict(val, "input_select/update"))
        self.logger.debug("Updated input_select helper %r", helper_id)
        return record

    async def delete_input_select(self, helper_id: str) -> None:
        """Delete an input_select helper.

        Args:
            helper_id: The ID of the helper to delete.
        """
        await _ws_helper_call(self, "input_select", "delete", input_select_id=helper_id)
        self.logger.debug("Deleted input_select helper %r", helper_id)

    async def list_input_datetimes(self) -> list[InputDatetimeRecord]:
        """List all stored input_datetime helpers.

        Returns:
            List of InputDatetimeRecord instances representing stored configs.
        """
        val = await _ws_helper_call(self, "input_datetime", "list")
        items = _expect_list(val, "input_datetime/list")
        self.logger.debug("Listed %d input_datetime helpers", len(items))
        return [InputDatetimeRecord.model_validate(item) for item in items]

    async def create_input_datetime(self, params: CreateInputDatetimeParams) -> InputDatetimeRecord:
        """Create a new input_datetime helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant.
        """
        val = await _ws_helper_call(self, "input_datetime", "create", **params.model_dump(exclude_unset=True))
        record = InputDatetimeRecord.model_validate(_expect_dict(val, "input_datetime/create"))
        self.logger.info("Created input_datetime helper %r", record.id)
        return record

    async def update_input_datetime(self, helper_id: str, params: UpdateInputDatetimeParams) -> InputDatetimeRecord:
        """Update an existing input_datetime helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record.
        """
        val = await _ws_helper_call(
            self,
            "input_datetime",
            "update",
            input_datetime_id=helper_id,
            **params.model_dump(exclude_unset=True),
        )
        record = InputDatetimeRecord.model_validate(_expect_dict(val, "input_datetime/update"))
        self.logger.debug("Updated input_datetime helper %r", helper_id)
        return record

    async def delete_input_datetime(self, helper_id: str) -> None:
        """Delete an input_datetime helper.

        Args:
            helper_id: The ID of the helper to delete.
        """
        await _ws_helper_call(self, "input_datetime", "delete", input_datetime_id=helper_id)
        self.logger.debug("Deleted input_datetime helper %r", helper_id)

    async def list_input_buttons(self) -> list[InputButtonRecord]:
        """List all stored input_button helpers.

        Returns:
            List of InputButtonRecord instances representing stored configs.
        """
        val = await _ws_helper_call(self, "input_button", "list")
        items = _expect_list(val, "input_button/list")
        self.logger.debug("Listed %d input_button helpers", len(items))
        return [InputButtonRecord.model_validate(item) for item in items]

    async def create_input_button(self, params: CreateInputButtonParams) -> InputButtonRecord:
        """Create a new input_button helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant.
        """
        val = await _ws_helper_call(self, "input_button", "create", **params.model_dump(exclude_unset=True))
        record = InputButtonRecord.model_validate(_expect_dict(val, "input_button/create"))
        self.logger.info("Created input_button helper %r", record.id)
        return record

    async def update_input_button(self, helper_id: str, params: UpdateInputButtonParams) -> InputButtonRecord:
        """Update an existing input_button helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record.
        """
        val = await _ws_helper_call(
            self,
            "input_button",
            "update",
            input_button_id=helper_id,
            **params.model_dump(exclude_unset=True),
        )
        record = InputButtonRecord.model_validate(_expect_dict(val, "input_button/update"))
        self.logger.debug("Updated input_button helper %r", helper_id)
        return record

    async def delete_input_button(self, helper_id: str) -> None:
        """Delete an input_button helper.

        Args:
            helper_id: The ID of the helper to delete.
        """
        await _ws_helper_call(self, "input_button", "delete", input_button_id=helper_id)
        self.logger.debug("Deleted input_button helper %r", helper_id)

    async def list_counters(self) -> list[CounterRecord]:
        """List all stored counter helpers.

        Returns:
            List of CounterRecord instances representing stored configs.
        """
        val = await _ws_helper_call(self, "counter", "list")
        items = _expect_list(val, "counter/list")
        self.logger.debug("Listed %d counter helpers", len(items))
        return [CounterRecord.model_validate(item) for item in items]

    async def create_counter(self, params: CreateCounterParams) -> CounterRecord:
        """Create a new counter helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant.
        """
        val = await _ws_helper_call(self, "counter", "create", **params.model_dump(exclude_unset=True))
        record = CounterRecord.model_validate(_expect_dict(val, "counter/create"))
        self.logger.info("Created counter helper %r", record.id)
        return record

    async def update_counter(self, helper_id: str, params: UpdateCounterParams) -> CounterRecord:
        """Update an existing counter helper (stored config, not live value).

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record.
        """
        val = await _ws_helper_call(
            self,
            "counter",
            "update",
            counter_id=helper_id,
            **params.model_dump(exclude_unset=True),
        )
        record = CounterRecord.model_validate(_expect_dict(val, "counter/update"))
        self.logger.debug("Updated counter helper %r", helper_id)
        return record

    async def delete_counter(self, helper_id: str) -> None:
        """Delete a counter helper.

        Args:
            helper_id: The ID of the helper to delete.
        """
        await _ws_helper_call(self, "counter", "delete", counter_id=helper_id)
        self.logger.debug("Deleted counter helper %r", helper_id)

    async def list_timers(self) -> list[TimerRecord]:
        """List all stored timer helpers.

        Returns:
            List of TimerRecord instances representing stored configs.
        """
        val = await _ws_helper_call(self, "timer", "list")
        items = _expect_list(val, "timer/list")
        self.logger.debug("Listed %d timer helpers", len(items))
        return [TimerRecord.model_validate(item) for item in items]

    async def create_timer(self, params: CreateTimerParams) -> TimerRecord:
        """Create a new timer helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant.
        """
        val = await _ws_helper_call(self, "timer", "create", **params.model_dump(exclude_unset=True))
        record = TimerRecord.model_validate(_expect_dict(val, "timer/create"))
        self.logger.info("Created timer helper %r", record.id)
        return record

    async def update_timer(self, helper_id: str, params: UpdateTimerParams) -> TimerRecord:
        """Update an existing timer helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record.
        """
        val = await _ws_helper_call(
            self,
            "timer",
            "update",
            timer_id=helper_id,
            **params.model_dump(exclude_unset=True),
        )
        record = TimerRecord.model_validate(_expect_dict(val, "timer/update"))
        self.logger.debug("Updated timer helper %r", helper_id)
        return record

    async def delete_timer(self, helper_id: str) -> None:
        """Delete a timer helper.

        Args:
            helper_id: The ID of the helper to delete.
        """
        await _ws_helper_call(self, "timer", "delete", timer_id=helper_id)
        self.logger.debug("Deleted timer helper %r", helper_id)

    # Counter service-call shortcuts (operate on live entity state, not stored
    # config). Use update_counter() to change the stored initial/minimum/maximum.
    #
    # timer.start / timer.pause / timer.cancel are deliberately excluded: timer
    # service actions are one-off calls that benefit from the full call_service()
    # signature. Counter actions get wrappers because the pattern "increment on
    # every event" is common enough to warrant a two-word call site.

    async def increment_counter(self, entity_id: str) -> None:
        """Increment a counter entity's current value (live state, not stored config).

        Args:
            entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``).
        """
        await self.call_service(
            "counter",
            "increment",
            target={"entity_id": entity_id},
            return_response=True,  # surfaces HA errors instead of fire-and-forget
        )
        self.logger.debug("Incremented counter %r", entity_id)

    async def decrement_counter(self, entity_id: str) -> None:
        """Decrement a counter entity's current value (live state, not stored config).

        Args:
            entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``).
        """
        await self.call_service(
            "counter",
            "decrement",
            target={"entity_id": entity_id},
            return_response=True,
        )
        self.logger.debug("Decremented counter %r", entity_id)

    async def reset_counter(self, entity_id: str) -> None:
        """Reset a counter entity's value to its configured initial (live state, not stored config).

        Args:
            entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``).
        """
        await self.call_service(
            "counter",
            "reset",
            target={"entity_id": entity_id},
            return_response=True,
        )
        self.logger.debug("Reset counter %r", entity_id)

sync: ApiSyncFacade = self.add_child(ApiSyncFacade, api=self) instance-attribute

Synchronous facade for the API service.

config_log_level: LOG_LEVEL_TYPE property

Return the log level from the config for this resource.

ws_send_and_wait(**data: Any) -> Any async

Send a WebSocket message and wait for a response.

Source code in src/hassette/api/api.py

async def ws_send_and_wait(self, **data: Any) -> Any:
    """Send a WebSocket message and wait for a response."""
    return await self._api_service._ws_conn.send_and_wait(**data)

ws_send_json(**data: Any) -> None async

Send a WebSocket message without waiting for a response.

Source code in src/hassette/api/api.py

async def ws_send_json(self, **data: Any) -> None:
    """Send a WebSocket message without waiting for a response."""
    await self._api_service._ws_conn.send_json(**data)

rest_request(method: str, url: str, params: dict[str, Any] | None = None, data: dict[str, Any] | None = None, suppress_error_message: bool = False, **kwargs: Any) -> aiohttp.ClientResponse async

Make a REST request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
method	str	The HTTP method to use (e.g., "GET", "POST").	required
url	str	The URL endpoint for the request.	required
params	dict[str, Any] | None	Query parameters for the request.	None
data	dict[str, Any] | None	JSON payload for the request.	None
suppress_error_message	bool	Whether to suppress error messages.	False

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/api.py

async def rest_request(
    self,
    method: str,
    url: str,
    params: dict[str, Any] | None = None,
    data: dict[str, Any] | None = None,
    suppress_error_message: bool = False,
    **kwargs: Any,
) -> aiohttp.ClientResponse:
    """Make a REST request to the Home Assistant API.

    Args:
        method: The HTTP method to use (e.g., "GET", "POST").
        url: The URL endpoint for the request.
        params: Query parameters for the request.
        data: JSON payload for the request.
        suppress_error_message: Whether to suppress error messages.

    Returns:
        The response from the API.
    """
    return await self._api_service._rest_request(
        method, url, params=params, data=data, suppress_error_message=suppress_error_message, **kwargs
    )

get_rest_request(url: str, params: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse async

Make a GET request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
url	str	The URL endpoint for the request.	required
params	dict[str, Any] | None	Query parameters for the request.	None
kwargs	Any	Additional keyword arguments to pass to the request.	{}

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/api.py

async def get_rest_request(
    self, url: str, params: dict[str, Any] | None = None, **kwargs: Any
) -> aiohttp.ClientResponse:
    """Make a GET request to the Home Assistant API.

    Args:
        url: The URL endpoint for the request.
        params: Query parameters for the request.
        kwargs: Additional keyword arguments to pass to the request.

    Returns:
        The response from the API.
    """
    return await self.rest_request("GET", url, params=params, **kwargs)

post_rest_request(url: str, data: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse async

Make a POST request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
url	str	The URL endpoint for the request.	required
data	dict[str, Any] | None	JSON payload for the request.	None
kwargs	Any	Additional keyword arguments to pass to the request.	{}

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/api.py

async def post_rest_request(
    self, url: str, data: dict[str, Any] | None = None, **kwargs: Any
) -> aiohttp.ClientResponse:
    """Make a POST request to the Home Assistant API.

    Args:
        url: The URL endpoint for the request.
        data: JSON payload for the request.
        kwargs: Additional keyword arguments to pass to the request.

    Returns:
        The response from the API.
    """
    return await self.rest_request("POST", url, data=data, **kwargs)

delete_rest_request(url: str, **kwargs: Any) -> aiohttp.ClientResponse async

Make a DELETE request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
url	str	The URL endpoint for the request.	required
kwargs	Any	Additional keyword arguments to pass to the request.	{}

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/api.py

async def delete_rest_request(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
    """Make a DELETE request to the Home Assistant API.

    Args:
        url: The URL endpoint for the request.
        kwargs: Additional keyword arguments to pass to the request.

    Returns:
        The response from the API.
    """
    return await self.rest_request("DELETE", url, **kwargs)

get_states_raw() -> list[HassStateDict] async

Get all entities in Home Assistant as raw dictionaries.

Returns:

Type	Description
list[HassStateDict]	A list of states as dictionaries.

Source code in src/hassette/api/api.py

async def get_states_raw(self) -> list["HassStateDict"]:
    """Get all entities in Home Assistant as raw dictionaries.

    Returns:
        A list of states as dictionaries.
    """
    val = await self.ws_send_and_wait(type="get_states")
    return _expect_list(val, "get_states")

get_states() -> list[BaseState] async

Get all entities in Home Assistant, converted to their appropriate state types.

If a state fails to convert, it is skipped with an error logged. If there is no registered state class for a domain, the generic BaseState is used.

Returns:

Type	Description
list[BaseState]	A list of states, converted to their appropriate state types.

Source code in src/hassette/api/api.py

async def get_states(self) -> list["BaseState"]:
    """Get all entities in Home Assistant, converted to their appropriate state types.

    If a state fails to convert, it is skipped with an error logged. If there is no registered
    state class for a domain, the generic BaseState is used.

    Returns:
        A list of states, converted to their appropriate state types.
    """
    val = await self.get_states_raw()

    self.logger.debug("Converting states to specific state types")
    converted: list[BaseState] = []

    for raw_state in val:
        # the conversion method will handle logging any conversion errors
        with suppress(UnableToConvertStateError):
            state = self.hassette.state_registry.try_convert_state(raw_state)
            converted.append(state)

    return converted

get_config() -> dict[str, Any] async

Get the Home Assistant configuration.

Returns:

Type	Description
dict[str, Any]	The configuration data.

Source code in src/hassette/api/api.py

async def get_config(self) -> dict[str, Any]:
    """Get the Home Assistant configuration.

    Returns:
        The configuration data.
    """
    val = await self.ws_send_and_wait(type="get_config")
    return _expect_dict(val, "get_config")

get_services() -> dict[str, Any] async

Get the available services in Home Assistant.

Returns:

Type	Description
dict[str, Any]	The services data.

Source code in src/hassette/api/api.py

async def get_services(self) -> dict[str, Any]:
    """Get the available services in Home Assistant.

    Returns:
        The services data.
    """
    val = await self.ws_send_and_wait(type="get_services")
    return _expect_dict(val, "get_services")

get_panels() -> dict[str, Any] async

Get the available panels in Home Assistant.

Returns:

Type	Description
dict[str, Any]	The panels data.

Source code in src/hassette/api/api.py

async def get_panels(self) -> dict[str, Any]:
    """Get the available panels in Home Assistant.

    Returns:
        The panels data.
    """
    val = await self.ws_send_and_wait(type="get_panels")
    return _expect_dict(val, "get_panels")

fire_event(event_type: str, event_data: dict[str, Any] | None = None) -> dict[str, Any] async

Fire a custom event in Home Assistant.

Parameters:

Name	Type	Description	Default
event_type	str	The type of the event to fire (e.g., "custom_event").	required
event_data	dict[str, Any] | None	Additional data to include with the event.	None

Returns:

Type	Description
dict[str, Any]	The response from Home Assistant.

Source code in src/hassette/api/api.py

async def fire_event(
    self,
    event_type: str,
    event_data: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Fire a custom event in Home Assistant.

    Args:
        event_type: The type of the event to fire (e.g., "custom_event").
        event_data: Additional data to include with the event.

    Returns:
        The response from Home Assistant.
    """
    event_data = event_data or {}

    data = {"type": "fire_event", "event_type": event_type, "event_data": event_data}
    if not event_data:
        data.pop("event_data")

    return await self.ws_send_and_wait(**data)

call_service(domain: str, service: str, target: dict[str, str] | dict[str, list[str]] | None = None, return_response: bool | None = False, **data: Any) -> ServiceResponse | None async

call_service(
    domain: str,
    service: str,
    target: dict[str, str] | dict[str, list[str]] | None,
    return_response: Literal[True],
    **data: Any,
) -> ServiceResponse

call_service(
    domain: str,
    service: str,
    target: dict[str, str]
    | dict[str, list[str]]
    | None = None,
    return_response: typing.Literal[False] | None = None,
    **data: Any,
) -> None

Call a Home Assistant service.

Parameters:

Name	Type	Description	Default
domain	str	The domain of the service (e.g., "light").	required
service	str	The name of the service to call (e.g., "turn_on").	required
target	dict[str, str] | dict[str, list[str]] | None	Target entity IDs or areas.	None
return_response	bool | None	Whether to return the response from Home Assistant. Defaults to False.	False
**data	Any	Additional data to send with the service call.	{}

Returns:

Type	Description
ServiceResponse | None	ServiceResponse | None: The response from Home Assistant if return_response is True. Otherwise None.

Source code in src/hassette/api/api.py

async def call_service(
    self,
    domain: str,
    service: str,
    target: dict[str, str] | dict[str, list[str]] | None = None,
    return_response: bool | None = False,
    **data: Any,
) -> ServiceResponse | None:
    """Call a Home Assistant service.

    Args:
        domain: The domain of the service (e.g., "light").
        service: The name of the service to call (e.g., "turn_on").
        target: Target entity IDs or areas.
        return_response: Whether to return the response from Home Assistant. Defaults to False.
        **data: Additional data to send with the service call.

    Returns:
        ServiceResponse | None: The response from Home Assistant if return_response is True. Otherwise None.
    """
    payload = {
        "type": "call_service",
        "domain": domain,
        "service": service,
        "target": target,
        "return_response": return_response,
    }

    payload = {k: v for k, v in payload.items() if v is not None}
    data = {k: v for k, v in data.items() if v is not None}

    if data:
        self.logger.debug("Adding extra data to service call: %s", data)
        payload["service_data"] = data

    if return_response:
        resp = await self.ws_send_and_wait(**payload)
        return ServiceResponse(**resp)

    await self.ws_send_json(**payload)
    return None

turn_on(entity_id: str | StrEnum, domain: str = 'homeassistant', **data: Any) -> None async

Turn on a specific entity in Home Assistant.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to turn on (e.g., "light.office").	required
domain	str	The domain to use for the service call (default: "homeassistant"). This calls the generic homeassistant.turn_on service, which is deprecated in Home Assistant 2024.x in favor of domain-specific services. For lights, pass domain="light"; for switches, pass domain="switch".	'homeassistant'

Source code in src/hassette/api/api.py

async def turn_on(self, entity_id: str | StrEnum, domain: str = "homeassistant", **data: Any) -> None:
    """Turn on a specific entity in Home Assistant.

    Args:
        entity_id: The ID of the entity to turn on (e.g., "light.office").
        domain: The domain to use for the service call (default: ``"homeassistant"``).
            This calls the generic ``homeassistant.turn_on`` service, which is deprecated
            in Home Assistant 2024.x in favor of domain-specific services. For lights,
            pass ``domain="light"``; for switches, pass ``domain="switch"``.

    """
    entity_id = str(entity_id)

    self.logger.debug("Turning on entity %s", entity_id)
    return await self.call_service(domain=domain, service="turn_on", target={"entity_id": entity_id}, **data)

turn_off(entity_id: str | StrEnum, domain: str = 'homeassistant') async

Turn off a specific entity in Home Assistant.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to turn off (e.g., "light.office").	required
domain	str	The domain to use for the service call (default: "homeassistant"). This calls the generic homeassistant.turn_off service, which is deprecated in Home Assistant 2024.x in favor of domain-specific services. For lights, pass domain="light"; for switches, pass domain="switch".	'homeassistant'

Source code in src/hassette/api/api.py

async def turn_off(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
    """Turn off a specific entity in Home Assistant.

    Args:
        entity_id: The ID of the entity to turn off (e.g., "light.office").
        domain: The domain to use for the service call (default: ``"homeassistant"``).
            This calls the generic ``homeassistant.turn_off`` service, which is deprecated
            in Home Assistant 2024.x in favor of domain-specific services. For lights,
            pass ``domain="light"``; for switches, pass ``domain="switch"``.

    """
    entity_id = str(entity_id)
    self.logger.debug("Turning off entity %s", entity_id)
    return await self.call_service(domain=domain, service="turn_off", target={"entity_id": entity_id})

toggle_service(entity_id: str | StrEnum, domain: str = 'homeassistant') async

Toggle a specific entity in Home Assistant.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to toggle (e.g., "light.office").	required
domain	str	The domain to use for the service call (default: "homeassistant"). This calls the generic homeassistant.toggle service, which is deprecated in Home Assistant 2024.x in favor of domain-specific services. For lights, pass domain="light"; for switches, pass domain="switch".	'homeassistant'

Source code in src/hassette/api/api.py

async def toggle_service(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
    """Toggle a specific entity in Home Assistant.

    Args:
        entity_id: The ID of the entity to toggle (e.g., "light.office").
        domain: The domain to use for the service call (default: ``"homeassistant"``).
            This calls the generic ``homeassistant.toggle`` service, which is deprecated
            in Home Assistant 2024.x in favor of domain-specific services. For lights,
            pass ``domain="light"``; for switches, pass ``domain="switch"``.

    """
    entity_id = str(entity_id)
    self.logger.debug("Toggling entity %s", entity_id)
    return await self.call_service(domain=domain, service="toggle", target={"entity_id": entity_id})

get_state_raw(entity_id: str) -> HassStateDict async

Get the state of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
HassStateDict	The state of the entity as raw data.

Source code in src/hassette/api/api.py

async def get_state_raw(self, entity_id: str) -> "HassStateDict":
    """Get the state of a specific entity.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity as raw data.
    """

    url = f"states/{entity_id}"
    response = await self.get_rest_request(url)
    return await response.json()

entity_exists(entity_id: str) -> bool async

Check if a specific entity exists.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to check.	required

Returns:

Type	Description
bool	True if the entity exists, False otherwise.

Source code in src/hassette/api/api.py

async def entity_exists(self, entity_id: str) -> bool:
    """Check if a specific entity exists.

    Args:
        entity_id: The ID of the entity to check.

    Returns:
        True if the entity exists, False otherwise.
    """

    try:
        url = f"states/{entity_id}"
        response = await self.rest_request("GET", url, suppress_error_message=True)
        await response.json()
        return True
    except EntityNotFoundError:
        return False

get_entity(entity_id: str, model: type[EntityT]) -> EntityT async

Get an entity object for a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get.	required
model	type[EntityT]	The model class to use for the entity.	required

Returns:

Type	Description
EntityT	The entity object.

Source code in src/hassette/api/api.py

async def get_entity(self, entity_id: str, model: type["EntityT"]) -> "EntityT":
    """Get an entity object for a specific entity.

    Args:
        entity_id: The ID of the entity to get.
        model: The model class to use for the entity.

    Returns:
        The entity object.
    """
    if not issubclass(model, BaseEntity):  # runtime check
        raise TypeError(f"Model {model!r} is not a valid BaseEntity subclass")

    raw = await self.get_state_raw(entity_id)

    return model.model_validate({"state": raw})

get_entity_or_none(entity_id: str, model: type[EntityT]) -> EntityT | None async

Get an entity object for a specific entity, or None if it does not exist.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get.	required
model	type[EntityT]	The model class to use for the entity.	required

Returns:

Type	Description
EntityT | None	The entity object, or None if it does not exist.

Source code in src/hassette/api/api.py

async def get_entity_or_none(self, entity_id: str, model: type["EntityT"]) -> "EntityT | None":
    """Get an entity object for a specific entity, or None if it does not exist.

    Args:
        entity_id: The ID of the entity to get.
        model: The model class to use for the entity.

    Returns:
        The entity object, or None if it does not exist.
    """
    try:
        return await self.get_entity(entity_id, model)
    except aiohttp.ClientResponseError as e:
        if e.status == 404:
            return None
        raise

get_state(entity_id: str) -> BaseState async

Get the state of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
BaseState	The state of the entity converted to the specified model type.

Source code in src/hassette/api/api.py

async def get_state(self, entity_id: str) -> "BaseState":
    """Get the state of a specific entity.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity converted to the specified model type.
    """

    raw = await self.get_state_raw(entity_id)
    return self.hassette.state_registry.try_convert_state(raw, entity_id)

get_state_or_none(entity_id: str) -> BaseState | None async

Get the state of a specific entity, or None if it does not exist.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
BaseState | None	The state of the entity converted to the specified model type, or None if it does not exist.

Source code in src/hassette/api/api.py

async def get_state_or_none(self, entity_id: str) -> "BaseState | None":
    """Get the state of a specific entity, or None if it does not exist.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity converted to the specified model type, or None if it does not exist.
    """
    try:
        return await self.get_state(entity_id)
    except aiohttp.ClientResponseError as e:
        if e.status == 404:
            return None
        raise

get_state_value(entity_id: str) -> Any async

Get the state of a specific entity without converting it to a state object.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
Any	The state of the entity as raw data.

Note

While most default methods in this library work with state objects for strong typing, this method is designed to return the raw state value, as it is likely overkill to convert it to a state object for simple state value retrieval.

Source code in src/hassette/api/api.py

async def get_state_value(self, entity_id: str) -> Any:
    """Get the state of a specific entity without converting it to a state object.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity as raw data.

    Note:
        While most default methods in this library work with state objects for
        strong typing, this method is designed to return the raw state value,
        as it is likely overkill to convert it to a state object for simple state value retrieval.
    """

    entity = await self.get_state_raw(entity_id)
    state = entity.get("state")
    return state

get_state_value_typed(entity_id: str) -> Any async

Get the value of a specific entity's state, converted to the correct type for that state.

The return type here is Any due to the dynamic nature of this conversion, but the return type at runtime will match the expected value type for the specific state class of the entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
Any	The state of the entity converted to the specified model type.

Raises:

Type	Description
TypeError	If the model is not a valid StateType subclass.

Warning

For states like SensorState the value type in Hassette is str, even if the sensor represents a number, as we cannot be sure of the actual type without additional context. For these cases, you are responsible for converting the string to the desired type.

Source code in src/hassette/api/api.py

async def get_state_value_typed(self, entity_id: str) -> "Any":
    """Get the value of a specific entity's state, converted to the correct type for that state.

    The return type here is Any due to the dynamic nature of this conversion, but the return type
    at runtime will match the expected value type for the specific state class of the entity.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity converted to the specified model type.

    Raises:
        TypeError: If the model is not a valid StateType subclass.

    Warning:
        For states like `SensorState` the value type in Hassette is `str`, even if the sensor represents a number,
        as we cannot be sure of the actual type without additional context. For these cases, you are responsible
        for converting the string to the desired type.
    """
    state_raw = await self.get_state_raw(entity_id)
    state = state_raw.get("state")

    model = self.hassette.state_registry.resolve(domain=entity_id.split(".")[0])
    if not model:
        return state
    return self.hassette.type_registry.convert(state, model.value_type)

get_attribute(entity_id: str, attribute: str) -> Any | FalseySentinel async

Get a specific attribute of an entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the attribute for.	required
attribute	str	The name of the attribute to retrieve. Can be a dot-separated path for nested attributes.	required

Returns:

Type	Description
Any | FalseySentinel	The value of the specified attribute, or MISSING_VALUE sentinel if the attribute does not exist.

Source code in src/hassette/api/api.py

async def get_attribute(self, entity_id: str, attribute: str) -> Any | FalseySentinel:
    """Get a specific attribute of an entity.

    Args:
        entity_id: The ID of the entity to get the attribute for.
        attribute: The name of the attribute to retrieve. Can be a dot-separated path for nested attributes.

    Returns:
        The value of the specified attribute, or MISSING_VALUE sentinel if the attribute does not exist.
    """

    entity = await self.get_state(entity_id)
    return get_path(attribute)(entity.attributes)

get_history(entity_id: str, start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str | None = None, significant_changes_only: bool = False, minimal_response: bool = False, no_attributes: bool = False) -> list[HistoryEntry] async

Get the history of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the history for.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the history range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str | None	The end time for the history range.	None
significant_changes_only	bool	Whether to only include significant changes.	False
minimal_response	bool	Whether to request a minimal response.	False
no_attributes	bool	Whether to exclude attributes from the response.	False

Returns:

Type	Description
list[HistoryEntry]	A list of history entries for the specified entity.

Source code in src/hassette/api/api.py

async def get_history(
    self,
    entity_id: str,
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
    significant_changes_only: bool = False,
    minimal_response: bool = False,
    no_attributes: bool = False,
) -> list[HistoryEntry]:
    """Get the history of a specific entity.

    Args:
        entity_id: The ID of the entity to get the history for.
        start_time: The start time for the history range.
        end_time: The end time for the history range.
        significant_changes_only: Whether to only include significant changes.
        minimal_response: Whether to request a minimal response.
        no_attributes: Whether to exclude attributes from the response.

    Returns:
        A list of history entries for the specified entity.
    """
    if "," in entity_id:
        raise ValueError("Entity ID should not contain commas. Use `get_histories` for multiple entities.")

    entries = await self._api_service._get_history_raw(
        entity_id=entity_id,
        start_time=start_time,
        end_time=end_time,
        significant_changes_only=significant_changes_only,
        minimal_response=minimal_response,
        no_attributes=no_attributes,
    )

    if not entries:
        return []

    assert len(entries) == 1, "Expected a single list of history entries"

    converted = [HistoryEntry.model_validate(entry) for entry in entries[0]]

    return converted

get_histories(entity_ids: list[str], start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str | None = None, significant_changes_only: bool = False, minimal_response: bool = False, no_attributes: bool = False) -> dict[str, list[HistoryEntry]] async

Get the history for multiple entities.

Parameters:

Name	Type	Description	Default
entity_ids	list[str]	The IDs of the entities to get the history for.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the history range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str | None	The end time for the history range.	None
significant_changes_only	bool	Whether to only include significant changes.	False
minimal_response	bool	Whether to request a minimal response.	False
no_attributes	bool	Whether to exclude attributes from the response.	False

Returns:

Type	Description
dict[str, list[HistoryEntry]]	A dictionary mapping entity IDs to their respective history entries.

Source code in src/hassette/api/api.py

async def get_histories(
    self,
    entity_ids: list[str],
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
    significant_changes_only: bool = False,
    minimal_response: bool = False,
    no_attributes: bool = False,
) -> dict[str, list[HistoryEntry]]:
    """Get the history for multiple entities.

    Args:
        entity_ids: The IDs of the entities to get the history for.
        start_time: The start time for the history range.
        end_time: The end time for the history range.
        significant_changes_only: Whether to only include significant changes.
        minimal_response: Whether to request a minimal response.
        no_attributes: Whether to exclude attributes from the response.

    Returns:
        A dictionary mapping entity IDs to their respective history entries.
    """
    entity_id = ",".join(entity_ids)

    entries = await self._api_service._get_history_raw(
        entity_id=entity_id,
        start_time=start_time,
        end_time=end_time,
        significant_changes_only=significant_changes_only,
        minimal_response=minimal_response,
        no_attributes=no_attributes,
    )

    if not entries:
        return {}

    converted = {}
    for history_list in entries:
        converted[history_list[0]["entity_id"]] = [HistoryEntry.model_validate(entry) for entry in history_list]

    return converted

get_logbook(entity_id: str, start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str) -> list[dict] async

Get the logbook entries for a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the logbook entries for.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the logbook range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str	The end time for the logbook range.	required

Returns:

Type	Description
list[dict]	A list of logbook entries for the specified entity.

Source code in src/hassette/api/api.py

async def get_logbook(
    self,
    entity_id: str,
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str,
) -> list[dict]:
    """Get the logbook entries for a specific entity.

    Args:
        entity_id: The ID of the entity to get the logbook entries for.
        start_time: The start time for the logbook range.
        end_time: The end time for the logbook range.

    Returns:
        A list of logbook entries for the specified entity.
    """

    url = f"logbook/{format_time_param(start_time)}"
    params = {"entity": entity_id, "end_time": end_time}

    response = await self.get_rest_request(url, params=params)

    return await response.json()

set_state(entity_id: str | StrEnum, state: Any, attributes: dict[str, Any] | None = None) -> dict async

Set the state of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to set the state for.	required
state	Any	The new state value to set.	required
attributes	dict[str, Any] | None	Additional attributes to set for the entity.	None

Returns:

Type	Description
dict	The response from Home Assistant after setting the state.

Source code in src/hassette/api/api.py

async def set_state(
    self,
    entity_id: str | StrEnum,
    state: Any,
    attributes: dict[str, Any] | None = None,
) -> dict:
    """Set the state of a specific entity.

    Args:
        entity_id: The ID of the entity to set the state for.
        state: The new state value to set.
        attributes: Additional attributes to set for the entity.

    Returns:
        The response from Home Assistant after setting the state.
    """

    entity_id = str(entity_id)

    attributes = attributes or {}
    curr_attributes = {}

    if await self.entity_exists(entity_id):
        curr_attributes = (await self.get_state_raw(entity_id)).get("attributes", {}) or {}

    # Merge current attributes with new attributes
    new_attributes = curr_attributes | attributes

    url = f"states/{entity_id}"
    data = {"state": state, "attributes": new_attributes}

    response = await self.post_rest_request(url, data=data)
    return await response.json()

get_camera_image(entity_id: str, timestamp: PlainDateTime | ZonedDateTime | Date | str | None = None) -> bytes async

Get the latest camera image for a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the camera entity to get the image for.	required
timestamp	PlainDateTime | ZonedDateTime | Date | str | None	The timestamp for the image. If None, the latest image is returned.	None

Returns:

Type	Description
bytes	The camera image data.

Source code in src/hassette/api/api.py

async def get_camera_image(
    self,
    entity_id: str,
    timestamp: PlainDateTime | ZonedDateTime | Date | str | None = None,
) -> bytes:
    """Get the latest camera image for a specific entity.

    Args:
        entity_id: The ID of the camera entity to get the image for.
        timestamp: The timestamp for the image. If None, the latest image is returned.

    Returns:
        The camera image data.
    """

    url = f"camera_proxy/{entity_id}"
    params = {}
    if timestamp:
        params["timestamp"] = timestamp

    response = await self.get_rest_request(url, params=params)

    return await response.read()

get_calendars() -> list[dict] async

Get the list of calendars.

Source code in src/hassette/api/api.py

async def get_calendars(self) -> list[dict]:
    """Get the list of calendars."""

    url = "calendars"
    response = await self.get_rest_request(url)
    return await response.json()

get_calendar_events(calendar_id: str, start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str) -> list[dict] async

Get events from a specific calendar.

Parameters:

Name	Type	Description	Default
calendar_id	str	The ID of the calendar to get events from.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the event range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str	The end time for the event range.	required

Returns:

Type	Description
list[dict]	A list of calendar events.

Source code in src/hassette/api/api.py

async def get_calendar_events(
    self,
    calendar_id: str,
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str,
) -> list[dict]:
    """Get events from a specific calendar.

    Args:
        calendar_id: The ID of the calendar to get events from.
        start_time: The start time for the event range.
        end_time: The end time for the event range.

    Returns:
        A list of calendar events.
    """

    url = f"calendars/{calendar_id}/events"
    params = {"start": start_time, "end": end_time}

    response = await self.get_rest_request(url, params=params)
    return await response.json()

render_template(template: str, variables: dict | None = None) -> str async

Render a template with given variables.

Parameters:

Name	Type	Description	Default
template	str	The template string to render.	required
variables	dict | None	Variables to use in the template.	None

Returns:

Type	Description
str	The rendered template result.

Source code in src/hassette/api/api.py

async def render_template(
    self,
    template: str,
    variables: dict | None = None,
) -> str:
    """Render a template with given variables.

    Args:
        template: The template string to render.
        variables: Variables to use in the template.

    Returns:
        The rendered template result.
    """

    url = "template"
    data = {"template": template, "variables": variables or {}}

    response = await self.post_rest_request(url, data=data)
    return await response.text()

delete_entity(entity_id: str) -> None async

Delete a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to delete.	required

Raises:

Type	Description
RuntimeError	If the deletion fails.

Source code in src/hassette/api/api.py

async def delete_entity(self, entity_id: str) -> None:
    """Delete a specific entity.

    Args:
        entity_id: The ID of the entity to delete.

    Raises:
        RuntimeError: If the deletion fails.
    """

    url = f"states/{entity_id}"

    response = await self.rest_request("DELETE", url)

    if response.status != 204:
        raise RuntimeError(f"Failed to delete entity {entity_id}: {response.status} - {response.reason}")

list_input_booleans() -> list[InputBooleanRecord] async

List all stored input_boolean helpers.

Returns:

Type	Description
list[InputBooleanRecord]	List of InputBooleanRecord instances representing stored configs.

Source code in src/hassette/api/api.py

async def list_input_booleans(self) -> list[InputBooleanRecord]:
    """List all stored input_boolean helpers.

    Returns:
        List of InputBooleanRecord instances representing stored configs.
    """
    val = await _ws_helper_call(self, "input_boolean", "list")
    items = _expect_list(val, "input_boolean/list")
    self.logger.debug("Listed %d input_boolean helpers", len(items))
    return [InputBooleanRecord.model_validate(item) for item in items]

create_input_boolean(params: CreateInputBooleanParams) -> InputBooleanRecord async

Create a new input_boolean helper.

Parameters:

Name	Type	Description	Default
params	CreateInputBooleanParams	Parameters for the new helper.	required

Returns:

Type	Description
InputBooleanRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/api.py

async def create_input_boolean(self, params: CreateInputBooleanParams) -> InputBooleanRecord:
    """Create a new input_boolean helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant.
    """
    val = await _ws_helper_call(self, "input_boolean", "create", **params.model_dump(exclude_unset=True))
    record = InputBooleanRecord.model_validate(_expect_dict(val, "input_boolean/create"))
    self.logger.info("Created input_boolean helper %r", record.id)
    return record

update_input_boolean(helper_id: str, params: UpdateInputBooleanParams) -> InputBooleanRecord async

Update an existing input_boolean helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputBooleanParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputBooleanRecord	The updated stored record.

Source code in src/hassette/api/api.py

async def update_input_boolean(self, helper_id: str, params: UpdateInputBooleanParams) -> InputBooleanRecord:
    """Update an existing input_boolean helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record.
    """
    val = await _ws_helper_call(
        self,
        "input_boolean",
        "update",
        input_boolean_id=helper_id,
        **params.model_dump(exclude_unset=True),
    )
    record = InputBooleanRecord.model_validate(_expect_dict(val, "input_boolean/update"))
    self.logger.debug("Updated input_boolean helper %r", helper_id)
    return record

delete_input_boolean(helper_id: str) -> None async

Delete an input_boolean helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/api.py

async def delete_input_boolean(self, helper_id: str) -> None:
    """Delete an input_boolean helper.

    Args:
        helper_id: The ID of the helper to delete.
    """
    await _ws_helper_call(self, "input_boolean", "delete", input_boolean_id=helper_id)
    self.logger.debug("Deleted input_boolean helper %r", helper_id)

list_input_numbers() -> list[InputNumberRecord] async

List all stored input_number helpers.

Returns:

Type	Description
list[InputNumberRecord]	List of InputNumberRecord instances representing stored configs.

Source code in src/hassette/api/api.py

async def list_input_numbers(self) -> list[InputNumberRecord]:
    """List all stored input_number helpers.

    Returns:
        List of InputNumberRecord instances representing stored configs.
    """
    val = await _ws_helper_call(self, "input_number", "list")
    items = _expect_list(val, "input_number/list")
    self.logger.debug("Listed %d input_number helpers", len(items))
    return [InputNumberRecord.model_validate(item) for item in items]

create_input_number(params: CreateInputNumberParams) -> InputNumberRecord async

Create a new input_number helper.

Parameters:

Name	Type	Description	Default
params	CreateInputNumberParams	Parameters for the new helper.	required

Returns:

Type	Description
InputNumberRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/api.py

async def create_input_number(self, params: CreateInputNumberParams) -> InputNumberRecord:
    """Create a new input_number helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant.
    """
    val = await _ws_helper_call(self, "input_number", "create", **params.model_dump(exclude_unset=True))
    record = InputNumberRecord.model_validate(_expect_dict(val, "input_number/create"))
    self.logger.info("Created input_number helper %r", record.id)
    return record

update_input_number(helper_id: str, params: UpdateInputNumberParams) -> InputNumberRecord async

Update an existing input_number helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputNumberParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputNumberRecord	The updated stored record.

Source code in src/hassette/api/api.py

async def update_input_number(self, helper_id: str, params: UpdateInputNumberParams) -> InputNumberRecord:
    """Update an existing input_number helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record.
    """
    val = await _ws_helper_call(
        self,
        "input_number",
        "update",
        input_number_id=helper_id,
        **params.model_dump(exclude_unset=True),
    )
    record = InputNumberRecord.model_validate(_expect_dict(val, "input_number/update"))
    self.logger.debug("Updated input_number helper %r", helper_id)
    return record

delete_input_number(helper_id: str) -> None async

Delete an input_number helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/api.py

async def delete_input_number(self, helper_id: str) -> None:
    """Delete an input_number helper.

    Args:
        helper_id: The ID of the helper to delete.
    """
    await _ws_helper_call(self, "input_number", "delete", input_number_id=helper_id)
    self.logger.debug("Deleted input_number helper %r", helper_id)

list_input_texts() -> list[InputTextRecord] async

List all stored input_text helpers.

Returns:

Type	Description
list[InputTextRecord]	List of InputTextRecord instances representing stored configs.

Source code in src/hassette/api/api.py

async def list_input_texts(self) -> list[InputTextRecord]:
    """List all stored input_text helpers.

    Returns:
        List of InputTextRecord instances representing stored configs.
    """
    val = await _ws_helper_call(self, "input_text", "list")
    items = _expect_list(val, "input_text/list")
    self.logger.debug("Listed %d input_text helpers", len(items))
    return [InputTextRecord.model_validate(item) for item in items]

create_input_text(params: CreateInputTextParams) -> InputTextRecord async

Create a new input_text helper.

Parameters:

Name	Type	Description	Default
params	CreateInputTextParams	Parameters for the new helper.	required

Returns:

Type	Description
InputTextRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/api.py

async def create_input_text(self, params: CreateInputTextParams) -> InputTextRecord:
    """Create a new input_text helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant.
    """
    val = await _ws_helper_call(self, "input_text", "create", **params.model_dump(exclude_unset=True))
    record = InputTextRecord.model_validate(_expect_dict(val, "input_text/create"))
    self.logger.info("Created input_text helper %r", record.id)
    return record

update_input_text(helper_id: str, params: UpdateInputTextParams) -> InputTextRecord async

Update an existing input_text helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputTextParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputTextRecord	The updated stored record.

Source code in src/hassette/api/api.py

async def update_input_text(self, helper_id: str, params: UpdateInputTextParams) -> InputTextRecord:
    """Update an existing input_text helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record.
    """
    val = await _ws_helper_call(
        self,
        "input_text",
        "update",
        input_text_id=helper_id,
        **params.model_dump(exclude_unset=True),
    )
    record = InputTextRecord.model_validate(_expect_dict(val, "input_text/update"))
    self.logger.debug("Updated input_text helper %r", helper_id)
    return record

delete_input_text(helper_id: str) -> None async

Delete an input_text helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/api.py

async def delete_input_text(self, helper_id: str) -> None:
    """Delete an input_text helper.

    Args:
        helper_id: The ID of the helper to delete.
    """
    await _ws_helper_call(self, "input_text", "delete", input_text_id=helper_id)
    self.logger.debug("Deleted input_text helper %r", helper_id)

list_input_selects() -> list[InputSelectRecord] async

List all stored input_select helpers.

Returns:

Type	Description
list[InputSelectRecord]	List of InputSelectRecord instances representing stored configs.

Source code in src/hassette/api/api.py

async def list_input_selects(self) -> list[InputSelectRecord]:
    """List all stored input_select helpers.

    Returns:
        List of InputSelectRecord instances representing stored configs.
    """
    val = await _ws_helper_call(self, "input_select", "list")
    items = _expect_list(val, "input_select/list")
    self.logger.debug("Listed %d input_select helpers", len(items))
    return [InputSelectRecord.model_validate(item) for item in items]

create_input_select(params: CreateInputSelectParams) -> InputSelectRecord async

Create a new input_select helper.

Parameters:

Name	Type	Description	Default
params	CreateInputSelectParams	Parameters for the new helper.	required

Returns:

Type	Description
InputSelectRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/api.py

async def create_input_select(self, params: CreateInputSelectParams) -> InputSelectRecord:
    """Create a new input_select helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant.
    """
    val = await _ws_helper_call(self, "input_select", "create", **params.model_dump(exclude_unset=True))
    record = InputSelectRecord.model_validate(_expect_dict(val, "input_select/create"))
    self.logger.info("Created input_select helper %r", record.id)
    return record

update_input_select(helper_id: str, params: UpdateInputSelectParams) -> InputSelectRecord async

Update an existing input_select helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputSelectParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputSelectRecord	The updated stored record.

Source code in src/hassette/api/api.py

async def update_input_select(self, helper_id: str, params: UpdateInputSelectParams) -> InputSelectRecord:
    """Update an existing input_select helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record.
    """
    val = await _ws_helper_call(
        self,
        "input_select",
        "update",
        input_select_id=helper_id,
        **params.model_dump(exclude_unset=True),
    )
    record = InputSelectRecord.model_validate(_expect_dict(val, "input_select/update"))
    self.logger.debug("Updated input_select helper %r", helper_id)
    return record

delete_input_select(helper_id: str) -> None async

Delete an input_select helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/api.py

async def delete_input_select(self, helper_id: str) -> None:
    """Delete an input_select helper.

    Args:
        helper_id: The ID of the helper to delete.
    """
    await _ws_helper_call(self, "input_select", "delete", input_select_id=helper_id)
    self.logger.debug("Deleted input_select helper %r", helper_id)

list_input_datetimes() -> list[InputDatetimeRecord] async

List all stored input_datetime helpers.

Returns:

Type	Description
list[InputDatetimeRecord]	List of InputDatetimeRecord instances representing stored configs.

Source code in src/hassette/api/api.py

async def list_input_datetimes(self) -> list[InputDatetimeRecord]:
    """List all stored input_datetime helpers.

    Returns:
        List of InputDatetimeRecord instances representing stored configs.
    """
    val = await _ws_helper_call(self, "input_datetime", "list")
    items = _expect_list(val, "input_datetime/list")
    self.logger.debug("Listed %d input_datetime helpers", len(items))
    return [InputDatetimeRecord.model_validate(item) for item in items]

create_input_datetime(params: CreateInputDatetimeParams) -> InputDatetimeRecord async

Create a new input_datetime helper.

Parameters:

Name	Type	Description	Default
params	CreateInputDatetimeParams	Parameters for the new helper.	required

Returns:

Type	Description
InputDatetimeRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/api.py

async def create_input_datetime(self, params: CreateInputDatetimeParams) -> InputDatetimeRecord:
    """Create a new input_datetime helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant.
    """
    val = await _ws_helper_call(self, "input_datetime", "create", **params.model_dump(exclude_unset=True))
    record = InputDatetimeRecord.model_validate(_expect_dict(val, "input_datetime/create"))
    self.logger.info("Created input_datetime helper %r", record.id)
    return record

update_input_datetime(helper_id: str, params: UpdateInputDatetimeParams) -> InputDatetimeRecord async

Update an existing input_datetime helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputDatetimeParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputDatetimeRecord	The updated stored record.

Source code in src/hassette/api/api.py

async def update_input_datetime(self, helper_id: str, params: UpdateInputDatetimeParams) -> InputDatetimeRecord:
    """Update an existing input_datetime helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record.
    """
    val = await _ws_helper_call(
        self,
        "input_datetime",
        "update",
        input_datetime_id=helper_id,
        **params.model_dump(exclude_unset=True),
    )
    record = InputDatetimeRecord.model_validate(_expect_dict(val, "input_datetime/update"))
    self.logger.debug("Updated input_datetime helper %r", helper_id)
    return record

delete_input_datetime(helper_id: str) -> None async

Delete an input_datetime helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/api.py

async def delete_input_datetime(self, helper_id: str) -> None:
    """Delete an input_datetime helper.

    Args:
        helper_id: The ID of the helper to delete.
    """
    await _ws_helper_call(self, "input_datetime", "delete", input_datetime_id=helper_id)
    self.logger.debug("Deleted input_datetime helper %r", helper_id)

list_input_buttons() -> list[InputButtonRecord] async

List all stored input_button helpers.

Returns:

Type	Description
list[InputButtonRecord]	List of InputButtonRecord instances representing stored configs.

Source code in src/hassette/api/api.py

async def list_input_buttons(self) -> list[InputButtonRecord]:
    """List all stored input_button helpers.

    Returns:
        List of InputButtonRecord instances representing stored configs.
    """
    val = await _ws_helper_call(self, "input_button", "list")
    items = _expect_list(val, "input_button/list")
    self.logger.debug("Listed %d input_button helpers", len(items))
    return [InputButtonRecord.model_validate(item) for item in items]

create_input_button(params: CreateInputButtonParams) -> InputButtonRecord async

Create a new input_button helper.

Parameters:

Name	Type	Description	Default
params	CreateInputButtonParams	Parameters for the new helper.	required

Returns:

Type	Description
InputButtonRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/api.py

async def create_input_button(self, params: CreateInputButtonParams) -> InputButtonRecord:
    """Create a new input_button helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant.
    """
    val = await _ws_helper_call(self, "input_button", "create", **params.model_dump(exclude_unset=True))
    record = InputButtonRecord.model_validate(_expect_dict(val, "input_button/create"))
    self.logger.info("Created input_button helper %r", record.id)
    return record

update_input_button(helper_id: str, params: UpdateInputButtonParams) -> InputButtonRecord async

Update an existing input_button helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputButtonParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputButtonRecord	The updated stored record.

Source code in src/hassette/api/api.py

async def update_input_button(self, helper_id: str, params: UpdateInputButtonParams) -> InputButtonRecord:
    """Update an existing input_button helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record.
    """
    val = await _ws_helper_call(
        self,
        "input_button",
        "update",
        input_button_id=helper_id,
        **params.model_dump(exclude_unset=True),
    )
    record = InputButtonRecord.model_validate(_expect_dict(val, "input_button/update"))
    self.logger.debug("Updated input_button helper %r", helper_id)
    return record

delete_input_button(helper_id: str) -> None async

Delete an input_button helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/api.py

async def delete_input_button(self, helper_id: str) -> None:
    """Delete an input_button helper.

    Args:
        helper_id: The ID of the helper to delete.
    """
    await _ws_helper_call(self, "input_button", "delete", input_button_id=helper_id)
    self.logger.debug("Deleted input_button helper %r", helper_id)

list_counters() -> list[CounterRecord] async

List all stored counter helpers.

Returns:

Type	Description
list[CounterRecord]	List of CounterRecord instances representing stored configs.

Source code in src/hassette/api/api.py

async def list_counters(self) -> list[CounterRecord]:
    """List all stored counter helpers.

    Returns:
        List of CounterRecord instances representing stored configs.
    """
    val = await _ws_helper_call(self, "counter", "list")
    items = _expect_list(val, "counter/list")
    self.logger.debug("Listed %d counter helpers", len(items))
    return [CounterRecord.model_validate(item) for item in items]

create_counter(params: CreateCounterParams) -> CounterRecord async

Create a new counter helper.

Parameters:

Name	Type	Description	Default
params	CreateCounterParams	Parameters for the new helper.	required

Returns:

Type	Description
CounterRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/api.py

async def create_counter(self, params: CreateCounterParams) -> CounterRecord:
    """Create a new counter helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant.
    """
    val = await _ws_helper_call(self, "counter", "create", **params.model_dump(exclude_unset=True))
    record = CounterRecord.model_validate(_expect_dict(val, "counter/create"))
    self.logger.info("Created counter helper %r", record.id)
    return record

update_counter(helper_id: str, params: UpdateCounterParams) -> CounterRecord async

Update an existing counter helper (stored config, not live value).

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateCounterParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
CounterRecord	The updated stored record.

Source code in src/hassette/api/api.py

async def update_counter(self, helper_id: str, params: UpdateCounterParams) -> CounterRecord:
    """Update an existing counter helper (stored config, not live value).

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record.
    """
    val = await _ws_helper_call(
        self,
        "counter",
        "update",
        counter_id=helper_id,
        **params.model_dump(exclude_unset=True),
    )
    record = CounterRecord.model_validate(_expect_dict(val, "counter/update"))
    self.logger.debug("Updated counter helper %r", helper_id)
    return record

delete_counter(helper_id: str) -> None async

Delete a counter helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/api.py

async def delete_counter(self, helper_id: str) -> None:
    """Delete a counter helper.

    Args:
        helper_id: The ID of the helper to delete.
    """
    await _ws_helper_call(self, "counter", "delete", counter_id=helper_id)
    self.logger.debug("Deleted counter helper %r", helper_id)

list_timers() -> list[TimerRecord] async

List all stored timer helpers.

Returns:

Type	Description
list[TimerRecord]	List of TimerRecord instances representing stored configs.

Source code in src/hassette/api/api.py

async def list_timers(self) -> list[TimerRecord]:
    """List all stored timer helpers.

    Returns:
        List of TimerRecord instances representing stored configs.
    """
    val = await _ws_helper_call(self, "timer", "list")
    items = _expect_list(val, "timer/list")
    self.logger.debug("Listed %d timer helpers", len(items))
    return [TimerRecord.model_validate(item) for item in items]

create_timer(params: CreateTimerParams) -> TimerRecord async

Create a new timer helper.

Parameters:

Name	Type	Description	Default
params	CreateTimerParams	Parameters for the new helper.	required

Returns:

Type	Description
TimerRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/api.py

async def create_timer(self, params: CreateTimerParams) -> TimerRecord:
    """Create a new timer helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant.
    """
    val = await _ws_helper_call(self, "timer", "create", **params.model_dump(exclude_unset=True))
    record = TimerRecord.model_validate(_expect_dict(val, "timer/create"))
    self.logger.info("Created timer helper %r", record.id)
    return record

update_timer(helper_id: str, params: UpdateTimerParams) -> TimerRecord async

Update an existing timer helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateTimerParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
TimerRecord	The updated stored record.

Source code in src/hassette/api/api.py

async def update_timer(self, helper_id: str, params: UpdateTimerParams) -> TimerRecord:
    """Update an existing timer helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record.
    """
    val = await _ws_helper_call(
        self,
        "timer",
        "update",
        timer_id=helper_id,
        **params.model_dump(exclude_unset=True),
    )
    record = TimerRecord.model_validate(_expect_dict(val, "timer/update"))
    self.logger.debug("Updated timer helper %r", helper_id)
    return record

delete_timer(helper_id: str) -> None async

Delete a timer helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/api.py

async def delete_timer(self, helper_id: str) -> None:
    """Delete a timer helper.

    Args:
        helper_id: The ID of the helper to delete.
    """
    await _ws_helper_call(self, "timer", "delete", timer_id=helper_id)
    self.logger.debug("Deleted timer helper %r", helper_id)

increment_counter(entity_id: str) -> None async

Increment a counter entity's current value (live state, not stored config).

Parameters:

Name	Type	Description	Default
entity_id	str	The entity ID of the counter (e.g. "counter.motion_count").	required

Source code in src/hassette/api/api.py

async def increment_counter(self, entity_id: str) -> None:
    """Increment a counter entity's current value (live state, not stored config).

    Args:
        entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``).
    """
    await self.call_service(
        "counter",
        "increment",
        target={"entity_id": entity_id},
        return_response=True,  # surfaces HA errors instead of fire-and-forget
    )
    self.logger.debug("Incremented counter %r", entity_id)

decrement_counter(entity_id: str) -> None async

Decrement a counter entity's current value (live state, not stored config).

Parameters:

Name	Type	Description	Default
entity_id	str	The entity ID of the counter (e.g. "counter.motion_count").	required

Source code in src/hassette/api/api.py

async def decrement_counter(self, entity_id: str) -> None:
    """Decrement a counter entity's current value (live state, not stored config).

    Args:
        entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``).
    """
    await self.call_service(
        "counter",
        "decrement",
        target={"entity_id": entity_id},
        return_response=True,
    )
    self.logger.debug("Decremented counter %r", entity_id)

reset_counter(entity_id: str) -> None async

Reset a counter entity's value to its configured initial (live state, not stored config).

Parameters:

Name	Type	Description	Default
entity_id	str	The entity ID of the counter (e.g. "counter.motion_count").	required

Source code in src/hassette/api/api.py

async def reset_counter(self, entity_id: str) -> None:
    """Reset a counter entity's value to its configured initial (live state, not stored config).

    Args:
        entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``).
    """
    await self.call_service(
        "counter",
        "reset",
        target={"entity_id": entity_id},
        return_response=True,
    )
    self.logger.debug("Reset counter %r", entity_id)

ApiSyncFacade

Bases: Resource

Synchronous facade for the API service.

This class provides synchronous methods that wrap the asynchronous methods of the Api class, allowing for blocking calls in a synchronous context.

These methods must not be called from within the event loop; doing so raises a RuntimeError. Use the asynchronous methods on Api directly when operating within an event loop.

Source code in src/hassette/api/sync.py

class ApiSyncFacade(Resource):
    """Synchronous facade for the API service.

    This class provides synchronous methods that wrap the asynchronous methods of the Api class,
    allowing for blocking calls in a synchronous context.

    These methods must not be called from within the event loop; doing so raises a RuntimeError.
    Use the asynchronous methods on ``Api`` directly when operating within an event loop.
    """

    _api: "Api"

    def __init__(self, hassette: "Hassette", *, api: "Api", parent: Resource | None = None) -> None:
        super().__init__(hassette, parent=parent)
        self._api = api

    async def on_initialize(self) -> None:
        self.mark_ready(reason="Synchronous API facade initialized")

    @property
    def config_log_level(self) -> LOG_LEVEL_TYPE:
        return self.hassette.config.logging.api

    def ws_send_and_wait(self, **data: Any) -> Any:
        """Send a WebSocket message and wait for a response."""

        return self.task_bucket.run_sync(self._api.ws_send_and_wait(**data))

    def ws_send_json(self, **data: Any) -> None:
        """Send a WebSocket message without waiting for a response."""

        return self.task_bucket.run_sync(self._api.ws_send_json(**data))

    def rest_request(
        self,
        method: str,
        url: str,
        params: dict[str, Any] | None = None,
        data: dict[str, Any] | None = None,
        suppress_error_message: bool = False,
        **kwargs: Any,
    ) -> aiohttp.ClientResponse:
        """Make a REST request to the Home Assistant API.

        Args:
            method: The HTTP method to use (e.g., "GET", "POST").
            url: The URL endpoint for the request.
            params: Query parameters for the request.
            data: JSON payload for the request.
            suppress_error_message: Whether to suppress error messages.

        Returns:
            The response from the API."""

        return self.task_bucket.run_sync(
            self._api.rest_request(method, url, params, data, suppress_error_message, **kwargs)
        )

    def get_rest_request(self, url: str, params: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse:
        """Make a GET request to the Home Assistant API.

        Args:
            url: The URL endpoint for the request.
            params: Query parameters for the request.
            kwargs: Additional keyword arguments to pass to the request.

        Returns:
            The response from the API."""

        return self.task_bucket.run_sync(self._api.get_rest_request(url, params, **kwargs))

    def post_rest_request(self, url: str, data: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse:
        """Make a POST request to the Home Assistant API.

        Args:
            url: The URL endpoint for the request.
            data: JSON payload for the request.
            kwargs: Additional keyword arguments to pass to the request.

        Returns:
            The response from the API."""

        return self.task_bucket.run_sync(self._api.post_rest_request(url, data, **kwargs))

    def delete_rest_request(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
        """Make a DELETE request to the Home Assistant API.

        Args:
            url: The URL endpoint for the request.
            kwargs: Additional keyword arguments to pass to the request.

        Returns:
            The response from the API."""

        return self.task_bucket.run_sync(self._api.delete_rest_request(url, **kwargs))

    def get_states_raw(self) -> list["HassStateDict"]:
        """Get all entities in Home Assistant as raw dictionaries.

        Returns:
            A list of states as dictionaries."""

        return self.task_bucket.run_sync(self._api.get_states_raw())

    def get_states(self) -> list["BaseState"]:
        """Get all entities in Home Assistant, converted to their appropriate state types.

        If a state fails to convert, it is skipped with an error logged. If there is no registered
        state class for a domain, the generic BaseState is used.

        Returns:
            A list of states, converted to their appropriate state types."""

        return self.task_bucket.run_sync(self._api.get_states())

    def get_config(self) -> dict[str, Any]:
        """Get the Home Assistant configuration.

        Returns:
            The configuration data."""

        return self.task_bucket.run_sync(self._api.get_config())

    def get_services(self) -> dict[str, Any]:
        """Get the available services in Home Assistant.

        Returns:
            The services data."""

        return self.task_bucket.run_sync(self._api.get_services())

    def get_panels(self) -> dict[str, Any]:
        """Get the available panels in Home Assistant.

        Returns:
            The panels data."""

        return self.task_bucket.run_sync(self._api.get_panels())

    def fire_event(self, event_type: str, event_data: dict[str, Any] | None = None) -> dict[str, Any]:
        """Fire a custom event in Home Assistant.

        Args:
            event_type: The type of the event to fire (e.g., "custom_event").
            event_data: Additional data to include with the event.

        Returns:
            The response from Home Assistant."""

        return self.task_bucket.run_sync(self._api.fire_event(event_type, event_data))

    def call_service(
        self,
        domain: str,
        service: str,
        target: dict[str, str] | dict[str, list[str]] | None = None,
        return_response: bool | None = False,
        **data: Any,
    ) -> ServiceResponse | None:
        """Call a Home Assistant service.

        Args:
            domain: The domain of the service (e.g., "light").
            service: The name of the service to call (e.g., "turn_on").
            target: Target entity IDs or areas.
            return_response: Whether to return the response from Home Assistant. Defaults to False.
            **data: Additional data to send with the service call.

        Returns:
            ServiceResponse | None: The response from Home Assistant if return_response is True. Otherwise None."""

        return self.task_bucket.run_sync(self._api.call_service(domain, service, target, return_response, **data))

    def turn_on(self, entity_id: str | StrEnum, domain: str = "homeassistant", **data: Any) -> None:
        """Turn on a specific entity in Home Assistant.

        Args:
            entity_id: The ID of the entity to turn on (e.g., "light.office").
            domain: The domain to use for the service call (default: ``"homeassistant"``).
                This calls the generic ``homeassistant.turn_on`` service, which is deprecated
                in Home Assistant 2024.x in favor of domain-specific services. For lights,
                pass ``domain="light"``; for switches, pass ``domain="switch"``."""

        return self.task_bucket.run_sync(self._api.turn_on(entity_id, domain, **data))

    def turn_off(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
        """Turn off a specific entity in Home Assistant.

        Args:
            entity_id: The ID of the entity to turn off (e.g., "light.office").
            domain: The domain to use for the service call (default: ``"homeassistant"``).
                This calls the generic ``homeassistant.turn_off`` service, which is deprecated
                in Home Assistant 2024.x in favor of domain-specific services. For lights,
                pass ``domain="light"``; for switches, pass ``domain="switch"``."""

        return self.task_bucket.run_sync(self._api.turn_off(entity_id, domain))

    def toggle_service(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
        """Toggle a specific entity in Home Assistant.

        Args:
            entity_id: The ID of the entity to toggle (e.g., "light.office").
            domain: The domain to use for the service call (default: ``"homeassistant"``).
                This calls the generic ``homeassistant.toggle`` service, which is deprecated
                in Home Assistant 2024.x in favor of domain-specific services. For lights,
                pass ``domain="light"``; for switches, pass ``domain="switch"``."""

        return self.task_bucket.run_sync(self._api.toggle_service(entity_id, domain))

    def get_state_raw(self, entity_id: str) -> "HassStateDict":
        """Get the state of a specific entity.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity as raw data."""

        return self.task_bucket.run_sync(self._api.get_state_raw(entity_id))

    def entity_exists(self, entity_id: str) -> bool:
        """Check if a specific entity exists.

        Args:
            entity_id: The ID of the entity to check.

        Returns:
            True if the entity exists, False otherwise."""

        return self.task_bucket.run_sync(self._api.entity_exists(entity_id))

    def get_entity(self, entity_id: str, model: type["EntityT"]) -> "EntityT":
        """Get an entity object for a specific entity.

        Args:
            entity_id: The ID of the entity to get.
            model: The model class to use for the entity.

        Returns:
            The entity object."""

        return self.task_bucket.run_sync(self._api.get_entity(entity_id, model))

    def get_entity_or_none(self, entity_id: str, model: type["EntityT"]) -> "EntityT | None":
        """Get an entity object for a specific entity, or None if it does not exist.

        Args:
            entity_id: The ID of the entity to get.
            model: The model class to use for the entity.

        Returns:
            The entity object, or None if it does not exist."""

        return self.task_bucket.run_sync(self._api.get_entity_or_none(entity_id, model))

    def get_state(self, entity_id: str) -> "BaseState":
        """Get the state of a specific entity.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity converted to the specified model type."""

        return self.task_bucket.run_sync(self._api.get_state(entity_id))

    def get_state_or_none(self, entity_id: str) -> "BaseState | None":
        """Get the state of a specific entity, or None if it does not exist.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity converted to the specified model type, or None if it does not exist."""

        return self.task_bucket.run_sync(self._api.get_state_or_none(entity_id))

    def get_state_value(self, entity_id: str) -> Any:
        """Get the state of a specific entity without converting it to a state object.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity as raw data.

        Note:
            While most default methods in this library work with state objects for
            strong typing, this method is designed to return the raw state value,
            as it is likely overkill to convert it to a state object for simple state value retrieval."""

        return self.task_bucket.run_sync(self._api.get_state_value(entity_id))

    def get_state_value_typed(self, entity_id: str) -> "Any":
        """Get the value of a specific entity's state, converted to the correct type for that state.

        The return type here is Any due to the dynamic nature of this conversion, but the return type
        at runtime will match the expected value type for the specific state class of the entity.

        Args:
            entity_id: The ID of the entity to get the state for.

        Returns:
            The state of the entity converted to the specified model type.

        Raises:
            TypeError: If the model is not a valid StateType subclass.

        Warning:
            For states like `SensorState` the value type in Hassette is `str`, even if the sensor represents a number,
            as we cannot be sure of the actual type without additional context. For these cases, you are responsible
            for converting the string to the desired type."""

        return self.task_bucket.run_sync(self._api.get_state_value_typed(entity_id))

    def get_attribute(self, entity_id: str, attribute: str) -> Any | FalseySentinel:
        """Get a specific attribute of an entity.

        Args:
            entity_id: The ID of the entity to get the attribute for.
            attribute: The name of the attribute to retrieve. Can be a dot-separated path for nested attributes.

        Returns:
            The value of the specified attribute, or MISSING_VALUE sentinel if the attribute does not exist."""

        return self.task_bucket.run_sync(self._api.get_attribute(entity_id, attribute))

    def get_history(
        self,
        entity_id: str,
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
        significant_changes_only: bool = False,
        minimal_response: bool = False,
        no_attributes: bool = False,
    ) -> list[HistoryEntry]:
        """Get the history of a specific entity.

        Args:
            entity_id: The ID of the entity to get the history for.
            start_time: The start time for the history range.
            end_time: The end time for the history range.
            significant_changes_only: Whether to only include significant changes.
            minimal_response: Whether to request a minimal response.
            no_attributes: Whether to exclude attributes from the response.

        Returns:
            A list of history entries for the specified entity."""

        return self.task_bucket.run_sync(
            self._api.get_history(
                entity_id, start_time, end_time, significant_changes_only, minimal_response, no_attributes
            )
        )

    def get_histories(
        self,
        entity_ids: list[str],
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
        significant_changes_only: bool = False,
        minimal_response: bool = False,
        no_attributes: bool = False,
    ) -> dict[str, list[HistoryEntry]]:
        """Get the history for multiple entities.

        Args:
            entity_ids: The IDs of the entities to get the history for.
            start_time: The start time for the history range.
            end_time: The end time for the history range.
            significant_changes_only: Whether to only include significant changes.
            minimal_response: Whether to request a minimal response.
            no_attributes: Whether to exclude attributes from the response.

        Returns:
            A dictionary mapping entity IDs to their respective history entries."""

        return self.task_bucket.run_sync(
            self._api.get_histories(
                entity_ids, start_time, end_time, significant_changes_only, minimal_response, no_attributes
            )
        )

    def get_logbook(
        self,
        entity_id: str,
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str,
    ) -> list[dict]:
        """Get the logbook entries for a specific entity.

        Args:
            entity_id: The ID of the entity to get the logbook entries for.
            start_time: The start time for the logbook range.
            end_time: The end time for the logbook range.

        Returns:
            A list of logbook entries for the specified entity."""

        return self.task_bucket.run_sync(self._api.get_logbook(entity_id, start_time, end_time))

    def set_state(self, entity_id: str | StrEnum, state: Any, attributes: dict[str, Any] | None = None) -> dict:
        """Set the state of a specific entity.

        Args:
            entity_id: The ID of the entity to set the state for.
            state: The new state value to set.
            attributes: Additional attributes to set for the entity.

        Returns:
            The response from Home Assistant after setting the state."""

        return self.task_bucket.run_sync(self._api.set_state(entity_id, state, attributes))

    def get_camera_image(
        self, entity_id: str, timestamp: PlainDateTime | ZonedDateTime | Date | str | None = None
    ) -> bytes:
        """Get the latest camera image for a specific entity.

        Args:
            entity_id: The ID of the camera entity to get the image for.
            timestamp: The timestamp for the image. If None, the latest image is returned.

        Returns:
            The camera image data."""

        return self.task_bucket.run_sync(self._api.get_camera_image(entity_id, timestamp))

    def get_calendars(self) -> list[dict]:
        """Get the list of calendars."""

        return self.task_bucket.run_sync(self._api.get_calendars())

    def get_calendar_events(
        self,
        calendar_id: str,
        start_time: PlainDateTime | ZonedDateTime | Date | str,
        end_time: PlainDateTime | ZonedDateTime | Date | str,
    ) -> list[dict]:
        """Get events from a specific calendar.

        Args:
            calendar_id: The ID of the calendar to get events from.
            start_time: The start time for the event range.
            end_time: The end time for the event range.

        Returns:
            A list of calendar events."""

        return self.task_bucket.run_sync(self._api.get_calendar_events(calendar_id, start_time, end_time))

    def render_template(self, template: str, variables: dict | None = None) -> str:
        """Render a template with given variables.

        Args:
            template: The template string to render.
            variables: Variables to use in the template.

        Returns:
            The rendered template result."""

        return self.task_bucket.run_sync(self._api.render_template(template, variables))

    def delete_entity(self, entity_id: str) -> None:
        """Delete a specific entity.

        Args:
            entity_id: The ID of the entity to delete.

        Raises:
            RuntimeError: If the deletion fails."""

        return self.task_bucket.run_sync(self._api.delete_entity(entity_id))

    def list_input_booleans(self) -> list[InputBooleanRecord]:
        """List all stored input_boolean helpers.

        Returns:
            List of InputBooleanRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_booleans())

    def create_input_boolean(self, params: CreateInputBooleanParams) -> InputBooleanRecord:
        """Create a new input_boolean helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_boolean(params))

    def update_input_boolean(self, helper_id: str, params: UpdateInputBooleanParams) -> InputBooleanRecord:
        """Update an existing input_boolean helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_boolean(helper_id, params))

    def delete_input_boolean(self, helper_id: str) -> None:
        """Delete an input_boolean helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_boolean(helper_id))

    def list_input_numbers(self) -> list[InputNumberRecord]:
        """List all stored input_number helpers.

        Returns:
            List of InputNumberRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_numbers())

    def create_input_number(self, params: CreateInputNumberParams) -> InputNumberRecord:
        """Create a new input_number helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_number(params))

    def update_input_number(self, helper_id: str, params: UpdateInputNumberParams) -> InputNumberRecord:
        """Update an existing input_number helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_number(helper_id, params))

    def delete_input_number(self, helper_id: str) -> None:
        """Delete an input_number helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_number(helper_id))

    def list_input_texts(self) -> list[InputTextRecord]:
        """List all stored input_text helpers.

        Returns:
            List of InputTextRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_texts())

    def create_input_text(self, params: CreateInputTextParams) -> InputTextRecord:
        """Create a new input_text helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_text(params))

    def update_input_text(self, helper_id: str, params: UpdateInputTextParams) -> InputTextRecord:
        """Update an existing input_text helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_text(helper_id, params))

    def delete_input_text(self, helper_id: str) -> None:
        """Delete an input_text helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_text(helper_id))

    def list_input_selects(self) -> list[InputSelectRecord]:
        """List all stored input_select helpers.

        Returns:
            List of InputSelectRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_selects())

    def create_input_select(self, params: CreateInputSelectParams) -> InputSelectRecord:
        """Create a new input_select helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_select(params))

    def update_input_select(self, helper_id: str, params: UpdateInputSelectParams) -> InputSelectRecord:
        """Update an existing input_select helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_select(helper_id, params))

    def delete_input_select(self, helper_id: str) -> None:
        """Delete an input_select helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_select(helper_id))

    def list_input_datetimes(self) -> list[InputDatetimeRecord]:
        """List all stored input_datetime helpers.

        Returns:
            List of InputDatetimeRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_datetimes())

    def create_input_datetime(self, params: CreateInputDatetimeParams) -> InputDatetimeRecord:
        """Create a new input_datetime helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_datetime(params))

    def update_input_datetime(self, helper_id: str, params: UpdateInputDatetimeParams) -> InputDatetimeRecord:
        """Update an existing input_datetime helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_datetime(helper_id, params))

    def delete_input_datetime(self, helper_id: str) -> None:
        """Delete an input_datetime helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_datetime(helper_id))

    def list_input_buttons(self) -> list[InputButtonRecord]:
        """List all stored input_button helpers.

        Returns:
            List of InputButtonRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_input_buttons())

    def create_input_button(self, params: CreateInputButtonParams) -> InputButtonRecord:
        """Create a new input_button helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_input_button(params))

    def update_input_button(self, helper_id: str, params: UpdateInputButtonParams) -> InputButtonRecord:
        """Update an existing input_button helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_input_button(helper_id, params))

    def delete_input_button(self, helper_id: str) -> None:
        """Delete an input_button helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_input_button(helper_id))

    def list_counters(self) -> list[CounterRecord]:
        """List all stored counter helpers.

        Returns:
            List of CounterRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_counters())

    def create_counter(self, params: CreateCounterParams) -> CounterRecord:
        """Create a new counter helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_counter(params))

    def update_counter(self, helper_id: str, params: UpdateCounterParams) -> CounterRecord:
        """Update an existing counter helper (stored config, not live value).

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_counter(helper_id, params))

    def delete_counter(self, helper_id: str) -> None:
        """Delete a counter helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_counter(helper_id))

    def list_timers(self) -> list[TimerRecord]:
        """List all stored timer helpers.

        Returns:
            List of TimerRecord instances representing stored configs."""

        return self.task_bucket.run_sync(self._api.list_timers())

    def create_timer(self, params: CreateTimerParams) -> TimerRecord:
        """Create a new timer helper.

        Args:
            params: Parameters for the new helper.

        Returns:
            The stored record returned by Home Assistant."""

        return self.task_bucket.run_sync(self._api.create_timer(params))

    def update_timer(self, helper_id: str, params: UpdateTimerParams) -> TimerRecord:
        """Update an existing timer helper.

        Args:
            helper_id: The ID of the helper to update.
            params: Fields to update (unset fields are left unchanged).

        Returns:
            The updated stored record."""

        return self.task_bucket.run_sync(self._api.update_timer(helper_id, params))

    def delete_timer(self, helper_id: str) -> None:
        """Delete a timer helper.

        Args:
            helper_id: The ID of the helper to delete."""

        return self.task_bucket.run_sync(self._api.delete_timer(helper_id))

    def increment_counter(self, entity_id: str) -> None:
        """Increment a counter entity's current value (live state, not stored config).

        Args:
            entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

        return self.task_bucket.run_sync(self._api.increment_counter(entity_id))

    def decrement_counter(self, entity_id: str) -> None:
        """Decrement a counter entity's current value (live state, not stored config).

        Args:
            entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

        return self.task_bucket.run_sync(self._api.decrement_counter(entity_id))

    def reset_counter(self, entity_id: str) -> None:
        """Reset a counter entity's value to its configured initial (live state, not stored config).

        Args:
            entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

        return self.task_bucket.run_sync(self._api.reset_counter(entity_id))

ws_send_and_wait(**data: Any) -> Any

Send a WebSocket message and wait for a response.

Source code in src/hassette/api/sync.py

def ws_send_and_wait(self, **data: Any) -> Any:
    """Send a WebSocket message and wait for a response."""

    return self.task_bucket.run_sync(self._api.ws_send_and_wait(**data))

ws_send_json(**data: Any) -> None

Send a WebSocket message without waiting for a response.

Source code in src/hassette/api/sync.py

def ws_send_json(self, **data: Any) -> None:
    """Send a WebSocket message without waiting for a response."""

    return self.task_bucket.run_sync(self._api.ws_send_json(**data))

rest_request(method: str, url: str, params: dict[str, Any] | None = None, data: dict[str, Any] | None = None, suppress_error_message: bool = False, **kwargs: Any) -> aiohttp.ClientResponse

Make a REST request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
method	str	The HTTP method to use (e.g., "GET", "POST").	required
url	str	The URL endpoint for the request.	required
params	dict[str, Any] | None	Query parameters for the request.	None
data	dict[str, Any] | None	JSON payload for the request.	None
suppress_error_message	bool	Whether to suppress error messages.	False

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/sync.py

def rest_request(
    self,
    method: str,
    url: str,
    params: dict[str, Any] | None = None,
    data: dict[str, Any] | None = None,
    suppress_error_message: bool = False,
    **kwargs: Any,
) -> aiohttp.ClientResponse:
    """Make a REST request to the Home Assistant API.

    Args:
        method: The HTTP method to use (e.g., "GET", "POST").
        url: The URL endpoint for the request.
        params: Query parameters for the request.
        data: JSON payload for the request.
        suppress_error_message: Whether to suppress error messages.

    Returns:
        The response from the API."""

    return self.task_bucket.run_sync(
        self._api.rest_request(method, url, params, data, suppress_error_message, **kwargs)
    )

get_rest_request(url: str, params: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse

Make a GET request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
url	str	The URL endpoint for the request.	required
params	dict[str, Any] | None	Query parameters for the request.	None
kwargs	Any	Additional keyword arguments to pass to the request.	{}

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/sync.py

def get_rest_request(self, url: str, params: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse:
    """Make a GET request to the Home Assistant API.

    Args:
        url: The URL endpoint for the request.
        params: Query parameters for the request.
        kwargs: Additional keyword arguments to pass to the request.

    Returns:
        The response from the API."""

    return self.task_bucket.run_sync(self._api.get_rest_request(url, params, **kwargs))

post_rest_request(url: str, data: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse

Make a POST request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
url	str	The URL endpoint for the request.	required
data	dict[str, Any] | None	JSON payload for the request.	None
kwargs	Any	Additional keyword arguments to pass to the request.	{}

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/sync.py

def post_rest_request(self, url: str, data: dict[str, Any] | None = None, **kwargs: Any) -> aiohttp.ClientResponse:
    """Make a POST request to the Home Assistant API.

    Args:
        url: The URL endpoint for the request.
        data: JSON payload for the request.
        kwargs: Additional keyword arguments to pass to the request.

    Returns:
        The response from the API."""

    return self.task_bucket.run_sync(self._api.post_rest_request(url, data, **kwargs))

delete_rest_request(url: str, **kwargs: Any) -> aiohttp.ClientResponse

Make a DELETE request to the Home Assistant API.

Parameters:

Name	Type	Description	Default
url	str	The URL endpoint for the request.	required
kwargs	Any	Additional keyword arguments to pass to the request.	{}

Returns:

Type	Description
ClientResponse	The response from the API.

Source code in src/hassette/api/sync.py

def delete_rest_request(self, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
    """Make a DELETE request to the Home Assistant API.

    Args:
        url: The URL endpoint for the request.
        kwargs: Additional keyword arguments to pass to the request.

    Returns:
        The response from the API."""

    return self.task_bucket.run_sync(self._api.delete_rest_request(url, **kwargs))

get_states_raw() -> list[HassStateDict]

Get all entities in Home Assistant as raw dictionaries.

Returns:

Type	Description
list[HassStateDict]	A list of states as dictionaries.

Source code in src/hassette/api/sync.py

def get_states_raw(self) -> list["HassStateDict"]:
    """Get all entities in Home Assistant as raw dictionaries.

    Returns:
        A list of states as dictionaries."""

    return self.task_bucket.run_sync(self._api.get_states_raw())

get_states() -> list[BaseState]

Get all entities in Home Assistant, converted to their appropriate state types.

If a state fails to convert, it is skipped with an error logged. If there is no registered state class for a domain, the generic BaseState is used.

Returns:

Type	Description
list[BaseState]	A list of states, converted to their appropriate state types.

Source code in src/hassette/api/sync.py

def get_states(self) -> list["BaseState"]:
    """Get all entities in Home Assistant, converted to their appropriate state types.

    If a state fails to convert, it is skipped with an error logged. If there is no registered
    state class for a domain, the generic BaseState is used.

    Returns:
        A list of states, converted to their appropriate state types."""

    return self.task_bucket.run_sync(self._api.get_states())

get_config() -> dict[str, Any]

Get the Home Assistant configuration.

Returns:

Type	Description
dict[str, Any]	The configuration data.

Source code in src/hassette/api/sync.py

def get_config(self) -> dict[str, Any]:
    """Get the Home Assistant configuration.

    Returns:
        The configuration data."""

    return self.task_bucket.run_sync(self._api.get_config())

get_services() -> dict[str, Any]

Get the available services in Home Assistant.

Returns:

Type	Description
dict[str, Any]	The services data.

Source code in src/hassette/api/sync.py

def get_services(self) -> dict[str, Any]:
    """Get the available services in Home Assistant.

    Returns:
        The services data."""

    return self.task_bucket.run_sync(self._api.get_services())

get_panels() -> dict[str, Any]

Get the available panels in Home Assistant.

Returns:

Type	Description
dict[str, Any]	The panels data.

Source code in src/hassette/api/sync.py

def get_panels(self) -> dict[str, Any]:
    """Get the available panels in Home Assistant.

    Returns:
        The panels data."""

    return self.task_bucket.run_sync(self._api.get_panels())

fire_event(event_type: str, event_data: dict[str, Any] | None = None) -> dict[str, Any]

Fire a custom event in Home Assistant.

Parameters:

Name	Type	Description	Default
event_type	str	The type of the event to fire (e.g., "custom_event").	required
event_data	dict[str, Any] | None	Additional data to include with the event.	None

Returns:

Type	Description
dict[str, Any]	The response from Home Assistant.

Source code in src/hassette/api/sync.py

def fire_event(self, event_type: str, event_data: dict[str, Any] | None = None) -> dict[str, Any]:
    """Fire a custom event in Home Assistant.

    Args:
        event_type: The type of the event to fire (e.g., "custom_event").
        event_data: Additional data to include with the event.

    Returns:
        The response from Home Assistant."""

    return self.task_bucket.run_sync(self._api.fire_event(event_type, event_data))

call_service(domain: str, service: str, target: dict[str, str] | dict[str, list[str]] | None = None, return_response: bool | None = False, **data: Any) -> ServiceResponse | None

Call a Home Assistant service.

Parameters:

Name	Type	Description	Default
domain	str	The domain of the service (e.g., "light").	required
service	str	The name of the service to call (e.g., "turn_on").	required
target	dict[str, str] | dict[str, list[str]] | None	Target entity IDs or areas.	None
return_response	bool | None	Whether to return the response from Home Assistant. Defaults to False.	False
**data	Any	Additional data to send with the service call.	{}

Returns:

Type	Description
ServiceResponse | None	ServiceResponse | None: The response from Home Assistant if return_response is True. Otherwise None.

Source code in src/hassette/api/sync.py

def call_service(
    self,
    domain: str,
    service: str,
    target: dict[str, str] | dict[str, list[str]] | None = None,
    return_response: bool | None = False,
    **data: Any,
) -> ServiceResponse | None:
    """Call a Home Assistant service.

    Args:
        domain: The domain of the service (e.g., "light").
        service: The name of the service to call (e.g., "turn_on").
        target: Target entity IDs or areas.
        return_response: Whether to return the response from Home Assistant. Defaults to False.
        **data: Additional data to send with the service call.

    Returns:
        ServiceResponse | None: The response from Home Assistant if return_response is True. Otherwise None."""

    return self.task_bucket.run_sync(self._api.call_service(domain, service, target, return_response, **data))

turn_on(entity_id: str | StrEnum, domain: str = 'homeassistant', **data: Any) -> None

Turn on a specific entity in Home Assistant.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to turn on (e.g., "light.office").	required
domain	str	The domain to use for the service call (default: "homeassistant"). This calls the generic homeassistant.turn_on service, which is deprecated in Home Assistant 2024.x in favor of domain-specific services. For lights, pass domain="light"; for switches, pass domain="switch".	'homeassistant'

Source code in src/hassette/api/sync.py

def turn_on(self, entity_id: str | StrEnum, domain: str = "homeassistant", **data: Any) -> None:
    """Turn on a specific entity in Home Assistant.

    Args:
        entity_id: The ID of the entity to turn on (e.g., "light.office").
        domain: The domain to use for the service call (default: ``"homeassistant"``).
            This calls the generic ``homeassistant.turn_on`` service, which is deprecated
            in Home Assistant 2024.x in favor of domain-specific services. For lights,
            pass ``domain="light"``; for switches, pass ``domain="switch"``."""

    return self.task_bucket.run_sync(self._api.turn_on(entity_id, domain, **data))

turn_off(entity_id: str | StrEnum, domain: str = 'homeassistant')

Turn off a specific entity in Home Assistant.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to turn off (e.g., "light.office").	required
domain	str	The domain to use for the service call (default: "homeassistant"). This calls the generic homeassistant.turn_off service, which is deprecated in Home Assistant 2024.x in favor of domain-specific services. For lights, pass domain="light"; for switches, pass domain="switch".	'homeassistant'

Source code in src/hassette/api/sync.py

def turn_off(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
    """Turn off a specific entity in Home Assistant.

    Args:
        entity_id: The ID of the entity to turn off (e.g., "light.office").
        domain: The domain to use for the service call (default: ``"homeassistant"``).
            This calls the generic ``homeassistant.turn_off`` service, which is deprecated
            in Home Assistant 2024.x in favor of domain-specific services. For lights,
            pass ``domain="light"``; for switches, pass ``domain="switch"``."""

    return self.task_bucket.run_sync(self._api.turn_off(entity_id, domain))

toggle_service(entity_id: str | StrEnum, domain: str = 'homeassistant')

Toggle a specific entity in Home Assistant.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to toggle (e.g., "light.office").	required
domain	str	The domain to use for the service call (default: "homeassistant"). This calls the generic homeassistant.toggle service, which is deprecated in Home Assistant 2024.x in favor of domain-specific services. For lights, pass domain="light"; for switches, pass domain="switch".	'homeassistant'

Source code in src/hassette/api/sync.py

def toggle_service(self, entity_id: str | StrEnum, domain: str = "homeassistant"):
    """Toggle a specific entity in Home Assistant.

    Args:
        entity_id: The ID of the entity to toggle (e.g., "light.office").
        domain: The domain to use for the service call (default: ``"homeassistant"``).
            This calls the generic ``homeassistant.toggle`` service, which is deprecated
            in Home Assistant 2024.x in favor of domain-specific services. For lights,
            pass ``domain="light"``; for switches, pass ``domain="switch"``."""

    return self.task_bucket.run_sync(self._api.toggle_service(entity_id, domain))

get_state_raw(entity_id: str) -> HassStateDict

Get the state of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
HassStateDict	The state of the entity as raw data.

Source code in src/hassette/api/sync.py

def get_state_raw(self, entity_id: str) -> "HassStateDict":
    """Get the state of a specific entity.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity as raw data."""

    return self.task_bucket.run_sync(self._api.get_state_raw(entity_id))

entity_exists(entity_id: str) -> bool

Check if a specific entity exists.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to check.	required

Returns:

Type	Description
bool	True if the entity exists, False otherwise.

Source code in src/hassette/api/sync.py

def entity_exists(self, entity_id: str) -> bool:
    """Check if a specific entity exists.

    Args:
        entity_id: The ID of the entity to check.

    Returns:
        True if the entity exists, False otherwise."""

    return self.task_bucket.run_sync(self._api.entity_exists(entity_id))

get_entity(entity_id: str, model: type[EntityT]) -> EntityT

Get an entity object for a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get.	required
model	type[EntityT]	The model class to use for the entity.	required

Returns:

Type	Description
EntityT	The entity object.

Source code in src/hassette/api/sync.py

def get_entity(self, entity_id: str, model: type["EntityT"]) -> "EntityT":
    """Get an entity object for a specific entity.

    Args:
        entity_id: The ID of the entity to get.
        model: The model class to use for the entity.

    Returns:
        The entity object."""

    return self.task_bucket.run_sync(self._api.get_entity(entity_id, model))

get_entity_or_none(entity_id: str, model: type[EntityT]) -> EntityT | None

Get an entity object for a specific entity, or None if it does not exist.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get.	required
model	type[EntityT]	The model class to use for the entity.	required

Returns:

Type	Description
EntityT | None	The entity object, or None if it does not exist.

Source code in src/hassette/api/sync.py

def get_entity_or_none(self, entity_id: str, model: type["EntityT"]) -> "EntityT | None":
    """Get an entity object for a specific entity, or None if it does not exist.

    Args:
        entity_id: The ID of the entity to get.
        model: The model class to use for the entity.

    Returns:
        The entity object, or None if it does not exist."""

    return self.task_bucket.run_sync(self._api.get_entity_or_none(entity_id, model))

get_state(entity_id: str) -> BaseState

Get the state of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
BaseState	The state of the entity converted to the specified model type.

Source code in src/hassette/api/sync.py

def get_state(self, entity_id: str) -> "BaseState":
    """Get the state of a specific entity.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity converted to the specified model type."""

    return self.task_bucket.run_sync(self._api.get_state(entity_id))

get_state_or_none(entity_id: str) -> BaseState | None

Get the state of a specific entity, or None if it does not exist.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
BaseState | None	The state of the entity converted to the specified model type, or None if it does not exist.

Source code in src/hassette/api/sync.py

def get_state_or_none(self, entity_id: str) -> "BaseState | None":
    """Get the state of a specific entity, or None if it does not exist.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity converted to the specified model type, or None if it does not exist."""

    return self.task_bucket.run_sync(self._api.get_state_or_none(entity_id))

get_state_value(entity_id: str) -> Any

Get the state of a specific entity without converting it to a state object.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
Any	The state of the entity as raw data.

Note

While most default methods in this library work with state objects for strong typing, this method is designed to return the raw state value, as it is likely overkill to convert it to a state object for simple state value retrieval.

Source code in src/hassette/api/sync.py

def get_state_value(self, entity_id: str) -> Any:
    """Get the state of a specific entity without converting it to a state object.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity as raw data.

    Note:
        While most default methods in this library work with state objects for
        strong typing, this method is designed to return the raw state value,
        as it is likely overkill to convert it to a state object for simple state value retrieval."""

    return self.task_bucket.run_sync(self._api.get_state_value(entity_id))

get_state_value_typed(entity_id: str) -> Any

Get the value of a specific entity's state, converted to the correct type for that state.

The return type here is Any due to the dynamic nature of this conversion, but the return type at runtime will match the expected value type for the specific state class of the entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the state for.	required

Returns:

Type	Description
Any	The state of the entity converted to the specified model type.

Raises:

Type	Description
TypeError	If the model is not a valid StateType subclass.

Warning

For states like SensorState the value type in Hassette is str, even if the sensor represents a number, as we cannot be sure of the actual type without additional context. For these cases, you are responsible for converting the string to the desired type.

Source code in src/hassette/api/sync.py

def get_state_value_typed(self, entity_id: str) -> "Any":
    """Get the value of a specific entity's state, converted to the correct type for that state.

    The return type here is Any due to the dynamic nature of this conversion, but the return type
    at runtime will match the expected value type for the specific state class of the entity.

    Args:
        entity_id: The ID of the entity to get the state for.

    Returns:
        The state of the entity converted to the specified model type.

    Raises:
        TypeError: If the model is not a valid StateType subclass.

    Warning:
        For states like `SensorState` the value type in Hassette is `str`, even if the sensor represents a number,
        as we cannot be sure of the actual type without additional context. For these cases, you are responsible
        for converting the string to the desired type."""

    return self.task_bucket.run_sync(self._api.get_state_value_typed(entity_id))

get_attribute(entity_id: str, attribute: str) -> Any | FalseySentinel

Get a specific attribute of an entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the attribute for.	required
attribute	str	The name of the attribute to retrieve. Can be a dot-separated path for nested attributes.	required

Returns:

Type	Description
Any | FalseySentinel	The value of the specified attribute, or MISSING_VALUE sentinel if the attribute does not exist.

Source code in src/hassette/api/sync.py

def get_attribute(self, entity_id: str, attribute: str) -> Any | FalseySentinel:
    """Get a specific attribute of an entity.

    Args:
        entity_id: The ID of the entity to get the attribute for.
        attribute: The name of the attribute to retrieve. Can be a dot-separated path for nested attributes.

    Returns:
        The value of the specified attribute, or MISSING_VALUE sentinel if the attribute does not exist."""

    return self.task_bucket.run_sync(self._api.get_attribute(entity_id, attribute))

get_history(entity_id: str, start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str | None = None, significant_changes_only: bool = False, minimal_response: bool = False, no_attributes: bool = False) -> list[HistoryEntry]

Get the history of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the history for.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the history range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str | None	The end time for the history range.	None
significant_changes_only	bool	Whether to only include significant changes.	False
minimal_response	bool	Whether to request a minimal response.	False
no_attributes	bool	Whether to exclude attributes from the response.	False

Returns:

Type	Description
list[HistoryEntry]	A list of history entries for the specified entity.

Source code in src/hassette/api/sync.py

def get_history(
    self,
    entity_id: str,
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
    significant_changes_only: bool = False,
    minimal_response: bool = False,
    no_attributes: bool = False,
) -> list[HistoryEntry]:
    """Get the history of a specific entity.

    Args:
        entity_id: The ID of the entity to get the history for.
        start_time: The start time for the history range.
        end_time: The end time for the history range.
        significant_changes_only: Whether to only include significant changes.
        minimal_response: Whether to request a minimal response.
        no_attributes: Whether to exclude attributes from the response.

    Returns:
        A list of history entries for the specified entity."""

    return self.task_bucket.run_sync(
        self._api.get_history(
            entity_id, start_time, end_time, significant_changes_only, minimal_response, no_attributes
        )
    )

get_histories(entity_ids: list[str], start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str | None = None, significant_changes_only: bool = False, minimal_response: bool = False, no_attributes: bool = False) -> dict[str, list[HistoryEntry]]

Get the history for multiple entities.

Parameters:

Name	Type	Description	Default
entity_ids	list[str]	The IDs of the entities to get the history for.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the history range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str | None	The end time for the history range.	None
significant_changes_only	bool	Whether to only include significant changes.	False
minimal_response	bool	Whether to request a minimal response.	False
no_attributes	bool	Whether to exclude attributes from the response.	False

Returns:

Type	Description
dict[str, list[HistoryEntry]]	A dictionary mapping entity IDs to their respective history entries.

Source code in src/hassette/api/sync.py

def get_histories(
    self,
    entity_ids: list[str],
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str | None = None,
    significant_changes_only: bool = False,
    minimal_response: bool = False,
    no_attributes: bool = False,
) -> dict[str, list[HistoryEntry]]:
    """Get the history for multiple entities.

    Args:
        entity_ids: The IDs of the entities to get the history for.
        start_time: The start time for the history range.
        end_time: The end time for the history range.
        significant_changes_only: Whether to only include significant changes.
        minimal_response: Whether to request a minimal response.
        no_attributes: Whether to exclude attributes from the response.

    Returns:
        A dictionary mapping entity IDs to their respective history entries."""

    return self.task_bucket.run_sync(
        self._api.get_histories(
            entity_ids, start_time, end_time, significant_changes_only, minimal_response, no_attributes
        )
    )

get_logbook(entity_id: str, start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str) -> list[dict]

Get the logbook entries for a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to get the logbook entries for.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the logbook range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str	The end time for the logbook range.	required

Returns:

Type	Description
list[dict]	A list of logbook entries for the specified entity.

Source code in src/hassette/api/sync.py

def get_logbook(
    self,
    entity_id: str,
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str,
) -> list[dict]:
    """Get the logbook entries for a specific entity.

    Args:
        entity_id: The ID of the entity to get the logbook entries for.
        start_time: The start time for the logbook range.
        end_time: The end time for the logbook range.

    Returns:
        A list of logbook entries for the specified entity."""

    return self.task_bucket.run_sync(self._api.get_logbook(entity_id, start_time, end_time))

set_state(entity_id: str | StrEnum, state: Any, attributes: dict[str, Any] | None = None) -> dict

Set the state of a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str | StrEnum	The ID of the entity to set the state for.	required
state	Any	The new state value to set.	required
attributes	dict[str, Any] | None	Additional attributes to set for the entity.	None

Returns:

Type	Description
dict	The response from Home Assistant after setting the state.

Source code in src/hassette/api/sync.py

def set_state(self, entity_id: str | StrEnum, state: Any, attributes: dict[str, Any] | None = None) -> dict:
    """Set the state of a specific entity.

    Args:
        entity_id: The ID of the entity to set the state for.
        state: The new state value to set.
        attributes: Additional attributes to set for the entity.

    Returns:
        The response from Home Assistant after setting the state."""

    return self.task_bucket.run_sync(self._api.set_state(entity_id, state, attributes))

get_camera_image(entity_id: str, timestamp: PlainDateTime | ZonedDateTime | Date | str | None = None) -> bytes

Get the latest camera image for a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the camera entity to get the image for.	required
timestamp	PlainDateTime | ZonedDateTime | Date | str | None	The timestamp for the image. If None, the latest image is returned.	None

Returns:

Type	Description
bytes	The camera image data.

Source code in src/hassette/api/sync.py

def get_camera_image(
    self, entity_id: str, timestamp: PlainDateTime | ZonedDateTime | Date | str | None = None
) -> bytes:
    """Get the latest camera image for a specific entity.

    Args:
        entity_id: The ID of the camera entity to get the image for.
        timestamp: The timestamp for the image. If None, the latest image is returned.

    Returns:
        The camera image data."""

    return self.task_bucket.run_sync(self._api.get_camera_image(entity_id, timestamp))

get_calendars() -> list[dict]

Get the list of calendars.

Source code in src/hassette/api/sync.py

def get_calendars(self) -> list[dict]:
    """Get the list of calendars."""

    return self.task_bucket.run_sync(self._api.get_calendars())

get_calendar_events(calendar_id: str, start_time: PlainDateTime | ZonedDateTime | Date | str, end_time: PlainDateTime | ZonedDateTime | Date | str) -> list[dict]

Get events from a specific calendar.

Parameters:

Name	Type	Description	Default
calendar_id	str	The ID of the calendar to get events from.	required
start_time	PlainDateTime | ZonedDateTime | Date | str	The start time for the event range.	required
end_time	PlainDateTime | ZonedDateTime | Date | str	The end time for the event range.	required

Returns:

Type	Description
list[dict]	A list of calendar events.

Source code in src/hassette/api/sync.py

def get_calendar_events(
    self,
    calendar_id: str,
    start_time: PlainDateTime | ZonedDateTime | Date | str,
    end_time: PlainDateTime | ZonedDateTime | Date | str,
) -> list[dict]:
    """Get events from a specific calendar.

    Args:
        calendar_id: The ID of the calendar to get events from.
        start_time: The start time for the event range.
        end_time: The end time for the event range.

    Returns:
        A list of calendar events."""

    return self.task_bucket.run_sync(self._api.get_calendar_events(calendar_id, start_time, end_time))

render_template(template: str, variables: dict | None = None) -> str

Render a template with given variables.

Parameters:

Name	Type	Description	Default
template	str	The template string to render.	required
variables	dict | None	Variables to use in the template.	None

Returns:

Type	Description
str	The rendered template result.

Source code in src/hassette/api/sync.py

def render_template(self, template: str, variables: dict | None = None) -> str:
    """Render a template with given variables.

    Args:
        template: The template string to render.
        variables: Variables to use in the template.

    Returns:
        The rendered template result."""

    return self.task_bucket.run_sync(self._api.render_template(template, variables))

delete_entity(entity_id: str) -> None

Delete a specific entity.

Parameters:

Name	Type	Description	Default
entity_id	str	The ID of the entity to delete.	required

Raises:

Type	Description
RuntimeError	If the deletion fails.

Source code in src/hassette/api/sync.py

def delete_entity(self, entity_id: str) -> None:
    """Delete a specific entity.

    Args:
        entity_id: The ID of the entity to delete.

    Raises:
        RuntimeError: If the deletion fails."""

    return self.task_bucket.run_sync(self._api.delete_entity(entity_id))

list_input_booleans() -> list[InputBooleanRecord]

List all stored input_boolean helpers.

Returns:

Type	Description
list[InputBooleanRecord]	List of InputBooleanRecord instances representing stored configs.

Source code in src/hassette/api/sync.py

def list_input_booleans(self) -> list[InputBooleanRecord]:
    """List all stored input_boolean helpers.

    Returns:
        List of InputBooleanRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_booleans())

create_input_boolean(params: CreateInputBooleanParams) -> InputBooleanRecord

Create a new input_boolean helper.

Parameters:

Name	Type	Description	Default
params	CreateInputBooleanParams	Parameters for the new helper.	required

Returns:

Type	Description
InputBooleanRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/sync.py

def create_input_boolean(self, params: CreateInputBooleanParams) -> InputBooleanRecord:
    """Create a new input_boolean helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_boolean(params))

update_input_boolean(helper_id: str, params: UpdateInputBooleanParams) -> InputBooleanRecord

Update an existing input_boolean helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputBooleanParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputBooleanRecord	The updated stored record.

Source code in src/hassette/api/sync.py

def update_input_boolean(self, helper_id: str, params: UpdateInputBooleanParams) -> InputBooleanRecord:
    """Update an existing input_boolean helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_boolean(helper_id, params))

delete_input_boolean(helper_id: str) -> None

Delete an input_boolean helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/sync.py

def delete_input_boolean(self, helper_id: str) -> None:
    """Delete an input_boolean helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_boolean(helper_id))

list_input_numbers() -> list[InputNumberRecord]

List all stored input_number helpers.

Returns:

Type	Description
list[InputNumberRecord]	List of InputNumberRecord instances representing stored configs.

Source code in src/hassette/api/sync.py

def list_input_numbers(self) -> list[InputNumberRecord]:
    """List all stored input_number helpers.

    Returns:
        List of InputNumberRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_numbers())

create_input_number(params: CreateInputNumberParams) -> InputNumberRecord

Create a new input_number helper.

Parameters:

Name	Type	Description	Default
params	CreateInputNumberParams	Parameters for the new helper.	required

Returns:

Type	Description
InputNumberRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/sync.py

def create_input_number(self, params: CreateInputNumberParams) -> InputNumberRecord:
    """Create a new input_number helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_number(params))

update_input_number(helper_id: str, params: UpdateInputNumberParams) -> InputNumberRecord

Update an existing input_number helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputNumberParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputNumberRecord	The updated stored record.

Source code in src/hassette/api/sync.py

def update_input_number(self, helper_id: str, params: UpdateInputNumberParams) -> InputNumberRecord:
    """Update an existing input_number helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_number(helper_id, params))

delete_input_number(helper_id: str) -> None

Delete an input_number helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/sync.py

def delete_input_number(self, helper_id: str) -> None:
    """Delete an input_number helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_number(helper_id))

list_input_texts() -> list[InputTextRecord]

List all stored input_text helpers.

Returns:

Type	Description
list[InputTextRecord]	List of InputTextRecord instances representing stored configs.

Source code in src/hassette/api/sync.py

def list_input_texts(self) -> list[InputTextRecord]:
    """List all stored input_text helpers.

    Returns:
        List of InputTextRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_texts())

create_input_text(params: CreateInputTextParams) -> InputTextRecord

Create a new input_text helper.

Parameters:

Name	Type	Description	Default
params	CreateInputTextParams	Parameters for the new helper.	required

Returns:

Type	Description
InputTextRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/sync.py

def create_input_text(self, params: CreateInputTextParams) -> InputTextRecord:
    """Create a new input_text helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_text(params))

update_input_text(helper_id: str, params: UpdateInputTextParams) -> InputTextRecord

Update an existing input_text helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputTextParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputTextRecord	The updated stored record.

Source code in src/hassette/api/sync.py

def update_input_text(self, helper_id: str, params: UpdateInputTextParams) -> InputTextRecord:
    """Update an existing input_text helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_text(helper_id, params))

delete_input_text(helper_id: str) -> None

Delete an input_text helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/sync.py

def delete_input_text(self, helper_id: str) -> None:
    """Delete an input_text helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_text(helper_id))

list_input_selects() -> list[InputSelectRecord]

List all stored input_select helpers.

Returns:

Type	Description
list[InputSelectRecord]	List of InputSelectRecord instances representing stored configs.

Source code in src/hassette/api/sync.py

def list_input_selects(self) -> list[InputSelectRecord]:
    """List all stored input_select helpers.

    Returns:
        List of InputSelectRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_selects())

create_input_select(params: CreateInputSelectParams) -> InputSelectRecord

Create a new input_select helper.

Parameters:

Name	Type	Description	Default
params	CreateInputSelectParams	Parameters for the new helper.	required

Returns:

Type	Description
InputSelectRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/sync.py

def create_input_select(self, params: CreateInputSelectParams) -> InputSelectRecord:
    """Create a new input_select helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_select(params))

update_input_select(helper_id: str, params: UpdateInputSelectParams) -> InputSelectRecord

Update an existing input_select helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputSelectParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputSelectRecord	The updated stored record.

Source code in src/hassette/api/sync.py

def update_input_select(self, helper_id: str, params: UpdateInputSelectParams) -> InputSelectRecord:
    """Update an existing input_select helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_select(helper_id, params))

delete_input_select(helper_id: str) -> None

Delete an input_select helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/sync.py

def delete_input_select(self, helper_id: str) -> None:
    """Delete an input_select helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_select(helper_id))

list_input_datetimes() -> list[InputDatetimeRecord]

List all stored input_datetime helpers.

Returns:

Type	Description
list[InputDatetimeRecord]	List of InputDatetimeRecord instances representing stored configs.

Source code in src/hassette/api/sync.py

def list_input_datetimes(self) -> list[InputDatetimeRecord]:
    """List all stored input_datetime helpers.

    Returns:
        List of InputDatetimeRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_datetimes())

create_input_datetime(params: CreateInputDatetimeParams) -> InputDatetimeRecord

Create a new input_datetime helper.

Parameters:

Name	Type	Description	Default
params	CreateInputDatetimeParams	Parameters for the new helper.	required

Returns:

Type	Description
InputDatetimeRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/sync.py

def create_input_datetime(self, params: CreateInputDatetimeParams) -> InputDatetimeRecord:
    """Create a new input_datetime helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_datetime(params))

update_input_datetime(helper_id: str, params: UpdateInputDatetimeParams) -> InputDatetimeRecord

Update an existing input_datetime helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputDatetimeParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputDatetimeRecord	The updated stored record.

Source code in src/hassette/api/sync.py

def update_input_datetime(self, helper_id: str, params: UpdateInputDatetimeParams) -> InputDatetimeRecord:
    """Update an existing input_datetime helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_datetime(helper_id, params))

delete_input_datetime(helper_id: str) -> None

Delete an input_datetime helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/sync.py

def delete_input_datetime(self, helper_id: str) -> None:
    """Delete an input_datetime helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_datetime(helper_id))

list_input_buttons() -> list[InputButtonRecord]

List all stored input_button helpers.

Returns:

Type	Description
list[InputButtonRecord]	List of InputButtonRecord instances representing stored configs.

Source code in src/hassette/api/sync.py

def list_input_buttons(self) -> list[InputButtonRecord]:
    """List all stored input_button helpers.

    Returns:
        List of InputButtonRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_input_buttons())

create_input_button(params: CreateInputButtonParams) -> InputButtonRecord

Create a new input_button helper.

Parameters:

Name	Type	Description	Default
params	CreateInputButtonParams	Parameters for the new helper.	required

Returns:

Type	Description
InputButtonRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/sync.py

def create_input_button(self, params: CreateInputButtonParams) -> InputButtonRecord:
    """Create a new input_button helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_input_button(params))

update_input_button(helper_id: str, params: UpdateInputButtonParams) -> InputButtonRecord

Update an existing input_button helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateInputButtonParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
InputButtonRecord	The updated stored record.

Source code in src/hassette/api/sync.py

def update_input_button(self, helper_id: str, params: UpdateInputButtonParams) -> InputButtonRecord:
    """Update an existing input_button helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_input_button(helper_id, params))

delete_input_button(helper_id: str) -> None

Delete an input_button helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/sync.py

def delete_input_button(self, helper_id: str) -> None:
    """Delete an input_button helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_input_button(helper_id))

list_counters() -> list[CounterRecord]

List all stored counter helpers.

Returns:

Type	Description
list[CounterRecord]	List of CounterRecord instances representing stored configs.

Source code in src/hassette/api/sync.py

def list_counters(self) -> list[CounterRecord]:
    """List all stored counter helpers.

    Returns:
        List of CounterRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_counters())

create_counter(params: CreateCounterParams) -> CounterRecord

Create a new counter helper.

Parameters:

Name	Type	Description	Default
params	CreateCounterParams	Parameters for the new helper.	required

Returns:

Type	Description
CounterRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/sync.py

def create_counter(self, params: CreateCounterParams) -> CounterRecord:
    """Create a new counter helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_counter(params))

update_counter(helper_id: str, params: UpdateCounterParams) -> CounterRecord

Update an existing counter helper (stored config, not live value).

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateCounterParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
CounterRecord	The updated stored record.

Source code in src/hassette/api/sync.py

def update_counter(self, helper_id: str, params: UpdateCounterParams) -> CounterRecord:
    """Update an existing counter helper (stored config, not live value).

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_counter(helper_id, params))

delete_counter(helper_id: str) -> None

Delete a counter helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/sync.py

def delete_counter(self, helper_id: str) -> None:
    """Delete a counter helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_counter(helper_id))

list_timers() -> list[TimerRecord]

List all stored timer helpers.

Returns:

Type	Description
list[TimerRecord]	List of TimerRecord instances representing stored configs.

Source code in src/hassette/api/sync.py

def list_timers(self) -> list[TimerRecord]:
    """List all stored timer helpers.

    Returns:
        List of TimerRecord instances representing stored configs."""

    return self.task_bucket.run_sync(self._api.list_timers())

create_timer(params: CreateTimerParams) -> TimerRecord

Create a new timer helper.

Parameters:

Name	Type	Description	Default
params	CreateTimerParams	Parameters for the new helper.	required

Returns:

Type	Description
TimerRecord	The stored record returned by Home Assistant.

Source code in src/hassette/api/sync.py

def create_timer(self, params: CreateTimerParams) -> TimerRecord:
    """Create a new timer helper.

    Args:
        params: Parameters for the new helper.

    Returns:
        The stored record returned by Home Assistant."""

    return self.task_bucket.run_sync(self._api.create_timer(params))

update_timer(helper_id: str, params: UpdateTimerParams) -> TimerRecord

Update an existing timer helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to update.	required
params	UpdateTimerParams	Fields to update (unset fields are left unchanged).	required

Returns:

Type	Description
TimerRecord	The updated stored record.

Source code in src/hassette/api/sync.py

def update_timer(self, helper_id: str, params: UpdateTimerParams) -> TimerRecord:
    """Update an existing timer helper.

    Args:
        helper_id: The ID of the helper to update.
        params: Fields to update (unset fields are left unchanged).

    Returns:
        The updated stored record."""

    return self.task_bucket.run_sync(self._api.update_timer(helper_id, params))

delete_timer(helper_id: str) -> None

Delete a timer helper.

Parameters:

Name	Type	Description	Default
helper_id	str	The ID of the helper to delete.	required

Source code in src/hassette/api/sync.py

def delete_timer(self, helper_id: str) -> None:
    """Delete a timer helper.

    Args:
        helper_id: The ID of the helper to delete."""

    return self.task_bucket.run_sync(self._api.delete_timer(helper_id))

increment_counter(entity_id: str) -> None

Increment a counter entity's current value (live state, not stored config).

Parameters:

Name	Type	Description	Default
entity_id	str	The entity ID of the counter (e.g. "counter.motion_count").	required

Source code in src/hassette/api/sync.py

def increment_counter(self, entity_id: str) -> None:
    """Increment a counter entity's current value (live state, not stored config).

    Args:
        entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

    return self.task_bucket.run_sync(self._api.increment_counter(entity_id))

decrement_counter(entity_id: str) -> None

Decrement a counter entity's current value (live state, not stored config).

Parameters:

Name	Type	Description	Default
entity_id	str	The entity ID of the counter (e.g. "counter.motion_count").	required

Source code in src/hassette/api/sync.py

def decrement_counter(self, entity_id: str) -> None:
    """Decrement a counter entity's current value (live state, not stored config).

    Args:
        entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

    return self.task_bucket.run_sync(self._api.decrement_counter(entity_id))

reset_counter(entity_id: str) -> None

Reset a counter entity's value to its configured initial (live state, not stored config).

Parameters:

Name	Type	Description	Default
entity_id	str	The entity ID of the counter (e.g. "counter.motion_count").	required

Source code in src/hassette/api/sync.py

def reset_counter(self, entity_id: str) -> None:
    """Reset a counter entity's value to its configured initial (live state, not stored config).

    Args:
        entity_id: The entity ID of the counter (e.g. ``"counter.motion_count"``)."""

    return self.task_bucket.run_sync(self._api.reset_counter(entity_id))