用途
ha-api 用于把外部系统与 Home Assistant 集成起来，覆盖 REST API 与 WebSocket API 两类接口。适合在需要发起 API 调用、管理实体状态、调用服务、订阅事件或进行实时通信时使用。
开始前的准备
资料建议在开始前先做一些准备工作：在 Home Assistant UI 中依次进入 Settings → My Home → Create Long-Lived Access Token 创建长期访问令牌，并把令牌存放在安全位置，例如环境变量，不要提交到 git。随后应先用 REST API 测试连接是否可用、令牌是否有效，再构建更复杂的集成。
两类 API 的选择
REST API 适用于一次性请求、状态查询、服务调用（HTTP 轮询）。WebSocket API 适用于实时事件、持续订阅，延迟更低（资料给出约 50ms 与秒级的对比）。文档建议根据场景选择：WebSocket 更适合实时应用，REST 对偶发请求更简单。
认证与关键规则
所有 API 请求都需要 Bearer 令牌认证。Authorization 头必须带 "Bearer " 前缀，且大小写与空格需准确。资料列出应当遵守的做法：把访问令牌存放到环境变量或安全保险库，绝不硬编码；先校验 WebSocket 的 auth_required 消息再发送其他命令；处理 HTTP 错误（401 表示令牌无效或过期，404 表示实体未找到，502 表示 Home Assistant 不可用）；调用服务时指定完整的 domain/service，例如 "light/turn_on"。同时列出不要做的事：不要把访问令牌提交到 git 或在日志中分享，不要跳过 WebSocket 初始认证握手，不要混用 Bearer 令牌认证与用户名密码，不要假定状态值总是字符串（可能是 "on"、123 或 null），不要用 entity_id 作路径参数调用服务端点，而应使用 JSON 请求体。
REST API 端点
资料列出主要端点：状态端点 GET /api/states 获取全部状态，GET /api/states/{entity_id} 获取单个实体状态，POST /api/states/{entity_id} 创建或更新实体状态（返回 201 Created 或 200 OK）；服务端点 GET /api/services 获取全部可用服务，POST /api/services/{domain}/{service} 调用服务；事件端点 GET /api/events 获取全部事件，POST /api/events/{event_type} 触发事件；历史端点 GET /api/history/period/{timestamp}?filter_entity_id={entity_id} 获取实体历史；配置端点 GET /api/config 获取 Home Assistant 配置；模板端点 POST /api/template 渲染模板。文档对每个端点给出了请求与响应示例。
WebSocket API
连接流程为：打开到 /api/websocket 的 WebSocket 连接；接收 auth_required 消息（需在 10 秒内响应）；发送带令牌的 auth 消息；接收 auth_ok 确认；发送订阅或命令；实时接收响应与事件。资料给出认证三条消息的示例，以及订阅事件（subscribe_events）、调用服务（call_service）、获取当前状态（get_states）、订阅特定触发器（subscribe_trigger）的命令格式与响应示例。
代码示例
资料提供 Python 的 REST API 示例（使用 requests，含获取状态、获取单个实体、调用服务与错误处理）和 WebSocket 示例（使用 aiohttp，含认证、订阅 state_changed 事件与事件循环监听）；提供 JavaScript 的 REST API 示例（使用 fetch）和 WebSocket 示例（浏览器 WebSocket，含认证与订阅 state_changed）；还提供 cURL 常用操作示例，包括获取全部实体、获取特定实体、开灯并设置亮度、关灯、设置气候温度、获取服务 schema、触发自动化、渲染模板。代码内容保持原样。
常见错误与预防
资料列出常见错误及对应方案：401 Unauthorized 多因令牌无效、过期或格式错误，应新建长期访问令牌并确认 Bearer 前缀；404 Not Found 多因实体不存在或 domain 错误，应通过 GET /api/states 核对 entity_id 并检查 domain.service 格式；WebSocket 认证超时多因未在 10 秒内响应 auth_required，应在收到后立即发送认证消息；属性混淆多因把 state 字符串与 attributes 对象混在一起，state 始终为字符串，attributes 包含 brightness 等元数据。
适用场景与限制
该技能适合需要与 Home Assistant 进行外部集成、状态管理、服务调用和实时事件订阅的开发或自动化场景。资料提到它可预防 5 类常见 API 集成错误，并比手动 API 发现节省约 30% 的 token，设置时间 2-5 分钟，而手动方式为 15-20 分钟。关于收费、价格、支持平台和具体效果，资料暂未提供。