> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# Core APIs

> Core classes and functions in Home Assistant

The `homeassistant.core` module contains the fundamental classes that power Home Assistant.

## HomeAssistant Class

The `HomeAssistant` class is the root object of the Home Assistant home automation system.

### Initialization

<ParamField path="config_dir" type="str" required>
  Path to the configuration directory
</ParamField>

```python theme={null}
from homeassistant.core import HomeAssistant

hass = HomeAssistant("/config")
```

### Key Attributes

<ResponseField name="data" type="HassDict">
  Dictionary that any component can store data on. This is the primary way to share data between components.
</ResponseField>

<ResponseField name="bus" type="EventBus">
  The event bus for firing and listening to events.
</ResponseField>

<ResponseField name="services" type="ServiceRegistry">
  The service registry for registering and calling services.
</ResponseField>

<ResponseField name="states" type="StateMachine">
  The state machine for tracking entity states.
</ResponseField>

<ResponseField name="config" type="Config">
  Configuration object containing Home Assistant settings.
</ResponseField>

<ResponseField name="state" type="CoreState">
  Current state of Home Assistant (NOT\_RUNNING, STARTING, RUNNING, STOPPING, STOPPED).
</ResponseField>

<ResponseField name="loop" type="asyncio.AbstractEventLoop">
  The asyncio event loop.
</ResponseField>

### Methods

#### async\_start()

Finalize startup from inside the event loop.

```python theme={null}
await hass.async_start()
```

#### async\_stop(exit\_code: int = 0, \*, force: bool = False)

Stop Home Assistant and shut down all threads.

<ParamField path="exit_code" type="int" default="0">
  Exit code to return
</ParamField>

<ParamField path="force" type="bool" default="False">
  Force stop regardless of current state
</ParamField>

```python theme={null}
await hass.async_stop()
```

#### async\_create\_task(target, name=None, eager\_start=True)

Create a task from within the event loop.

<ParamField path="target" type="Coroutine" required>
  Coroutine to execute
</ParamField>

<ParamField path="name" type="str">
  Name for the task (useful for debugging)
</ParamField>

<ParamField path="eager_start" type="bool" default="True">
  Whether to start the task eagerly
</ParamField>

<ResponseField name="return" type="asyncio.Task">
  The created task
</ResponseField>

```python theme={null}
task = hass.async_create_task(
    my_coroutine(),
    name="my_task"
)
```

#### async\_create\_background\_task(target, name, eager\_start=True)

Create a background task that won't block startup or shutdown.

<ParamField path="target" type="Coroutine" required>
  Coroutine to execute
</ParamField>

<ParamField path="name" type="str" required>
  Name for the task
</ParamField>

<ParamField path="eager_start" type="bool" default="True">
  Whether to start the task eagerly
</ParamField>

```python theme={null}
task = hass.async_create_background_task(
    long_running_task(),
    name="background_worker"
)
```

#### async\_add\_executor\_job(target, \*args)

Add an executor job from within the event loop.

<ParamField path="target" type="Callable" required>
  Function to execute in the executor
</ParamField>

<ParamField path="*args" type="Any">
  Arguments to pass to the function
</ParamField>

```python theme={null}
result = await hass.async_add_executor_job(
    blocking_function,
    arg1,
    arg2
)
```

## State Class

Represents the state of an entity.

### Initialization

<ParamField path="entity_id" type="str" required>
  The entity ID (format: domain.object\_id)
</ParamField>

<ParamField path="state" type="str" required>
  The state value
</ParamField>

<ParamField path="attributes" type="Mapping[str, Any]">
  Additional attributes for the state
</ParamField>

<ParamField path="last_changed" type="datetime">
  When the state was last changed
</ParamField>

<ParamField path="last_updated" type="datetime">
  When the state or attributes were last updated
</ParamField>

<ParamField path="context" type="Context">
  Context in which the state was created
</ParamField>

```python theme={null}
from homeassistant.core import State

state = State(
    "light.living_room",
    "on",
    {"brightness": 255, "color_temp": 400}
)
```

### Attributes

<ResponseField name="entity_id" type="str">
  The entity ID
</ResponseField>

<ResponseField name="state" type="str">
  The state value
</ResponseField>

<ResponseField name="attributes" type="ReadOnlyDict[str, Any]">
  Read-only dictionary of attributes
</ResponseField>

<ResponseField name="domain" type="str">
  Domain portion of the entity ID
</ResponseField>

<ResponseField name="object_id" type="str">
  Object ID portion of the entity ID
</ResponseField>

<ResponseField name="last_changed" type="datetime">
  When the state was last changed
</ResponseField>

<ResponseField name="last_updated" type="datetime">
  When the state or attributes were last updated
</ResponseField>

<ResponseField name="last_reported" type="datetime">
  Last time the state was reported
</ResponseField>

<ResponseField name="context" type="Context">
  Context object containing user\_id, parent\_id, and id
</ResponseField>

### Methods

#### as\_dict()

Return a read-only dictionary representation of the state.

```python theme={null}
state_dict = state.as_dict()
# Returns: {"entity_id": "...", "state": "...", "attributes": {...}, ...}
```

## Event Class

Represents an event within the event bus.

### Initialization

<ParamField path="event_type" type="str" required>
  Type of the event
</ParamField>

<ParamField path="data" type="Mapping[str, Any]">
  Event data
</ParamField>

<ParamField path="origin" type="EventOrigin" default="EventOrigin.local">
  Origin of the event (local or remote)
</ParamField>

<ParamField path="context" type="Context">
  Context in which the event was fired
</ParamField>

```python theme={null}
from homeassistant.core import Event, EventOrigin

event = Event(
    "my_event",
    {"some_key": "some_value"},
    EventOrigin.local
)
```

### Attributes

<ResponseField name="event_type" type="str">
  Type of the event
</ResponseField>

<ResponseField name="data" type="Mapping[str, Any]">
  Event data dictionary
</ResponseField>

<ResponseField name="origin" type="EventOrigin">
  Origin of the event (local or remote)
</ResponseField>

<ResponseField name="time_fired" type="datetime">
  When the event was fired
</ResponseField>

<ResponseField name="context" type="Context">
  Context object
</ResponseField>

## ServiceCall Class

Represents a call to a service.

### Initialization

<ParamField path="hass" type="HomeAssistant" required>
  Home Assistant instance
</ParamField>

<ParamField path="domain" type="str" required>
  Domain of the service
</ParamField>

<ParamField path="service" type="str" required>
  Name of the service
</ParamField>

<ParamField path="data" type="dict[str, Any]">
  Service call data
</ParamField>

<ParamField path="context" type="Context">
  Context for the service call
</ParamField>

<ParamField path="return_response" type="bool" default="False">
  Whether to return a response
</ParamField>

```python theme={null}
from homeassistant.core import ServiceCall

call = ServiceCall(
    hass,
    "light",
    "turn_on",
    {"entity_id": "light.living_room", "brightness": 255}
)
```

### Attributes

<ResponseField name="domain" type="str">
  Service domain
</ResponseField>

<ResponseField name="service" type="str">
  Service name
</ResponseField>

<ResponseField name="data" type="ReadOnlyDict[str, Any]">
  Service call data
</ResponseField>

<ResponseField name="context" type="Context">
  Context object
</ResponseField>

<ResponseField name="return_response" type="bool">
  Whether a response is expected
</ResponseField>

## Context Class

Represents the context that triggered something.

### Initialization

<ParamField path="user_id" type="str">
  ID of the user who triggered the action
</ParamField>

<ParamField path="parent_id" type="str">
  ID of the parent context
</ParamField>

<ParamField path="id" type="str">
  Unique ID for this context (auto-generated if not provided)
</ParamField>

```python theme={null}
from homeassistant.core import Context

context = Context(user_id="abc123")
```

### Attributes

<ResponseField name="id" type="str">
  Unique context ID (ULID format)
</ResponseField>

<ResponseField name="user_id" type="str | None">
  User ID if triggered by a user
</ResponseField>

<ResponseField name="parent_id" type="str | None">
  Parent context ID if this is a child context
</ResponseField>

## Helper Functions

### callback(func)

Decorator to mark a method as safe to call from within the event loop.

```python theme={null}
from homeassistant.core import callback

@callback
def my_callback_function():
    # This function is safe to call from the event loop
    pass
```

### async\_get\_hass()

Return the HomeAssistant instance from within the event loop.

```python theme={null}
from homeassistant.core import async_get_hass, callback

@callback
def my_function():
    hass = async_get_hass()
    # Use hass...
```

<Warning>
  This function raises `HomeAssistantError` if called from the wrong thread. Use sparingly and prefer passing the hass instance as a parameter.
</Warning>

### split\_entity\_id(entity\_id: str)

Split a state entity ID into domain and object ID.

<ParamField path="entity_id" type="str" required>
  Entity ID to split
</ParamField>

<ResponseField name="return" type="tuple[str, str]">
  Tuple of (domain, object\_id)
</ResponseField>

```python theme={null}
from homeassistant.core import split_entity_id

domain, object_id = split_entity_id("light.living_room")
# domain = "light", object_id = "living_room"
```

### valid\_entity\_id(entity\_id: str)

Test if an entity ID is in a valid format.

```python theme={null}
from homeassistant.core import valid_entity_id

if valid_entity_id("light.living_room"):
    print("Valid!")
```

## CoreState Enum

Represents the current state of Home Assistant.

<ResponseField name="not_running" type="str">
  Home Assistant is not running
</ResponseField>

<ResponseField name="starting" type="str">
  Home Assistant is starting up
</ResponseField>

<ResponseField name="running" type="str">
  Home Assistant is running
</ResponseField>

<ResponseField name="stopping" type="str">
  Home Assistant is stopping
</ResponseField>

<ResponseField name="final_write" type="str">
  Final write stage during shutdown
</ResponseField>

<ResponseField name="stopped" type="str">
  Home Assistant has stopped
</ResponseField>

## EventOrigin Enum

Represents the origin of an event.

<ResponseField name="local" type="str">
  Event originated locally
</ResponseField>

<ResponseField name="remote" type="str">
  Event originated from a remote source
</ResponseField>