用途：在 Home Assistant 之外以编程方式访问其 REST API，用于实体发现、状态读取与服务调用，适合构建自定义集成、自动化工具或外部数据采集。
主要能力：获取全部实体状态（/api/states）并按域名或关键字过滤；读取单个实体完整状态与属性（/api/states/{entity_id}）；调用服务控制设备（/api/services/{domain}/{service}），如 light.turn_on、climate.set_temperature、switch.turn_on；查询可用服务（/api/services）与配置（/api/config）。
使用方式：所有请求需长期访问令牌，通过 Authorization: Bearer $HA_LONG_LIVED_TOKEN 头认证。可用 Python requests 封装函数，也可用 curl 配合 jq 过滤。示例：curl -s "$HA_URL/api/states" -H "Authorization: Bearer $HA_LONG_LIVED_TOKEN" | jq。服务调用示例：curl -X POST "$HA_URL/api/services/light/turn_on" -H "Authorization: Bearer $HA_LONG_LIVED_TOKEN" -H "Content-Type: application/json" -d '{"entity_id": "light.living_room_dimmer", "brightness": 150}'。
适用场景：批量监控传感器、外部系统读取实体状态、脚本化控制设备、批量服务调用。
限制：不适用于可用内置自动化引擎实现的场景；实时仪表盘或仪表盘管理应改用 WebSocket API。需自行处理 401、404、超时等错误。具体端点细节可参考 references/api_endpoints.md。