REST API

服务端接口：clients（含 token 签发 / ephemeral）/ agents / usage

所有 REST 接口在 /api/v1/*，用 Authorization: Bearer <工作空间 API Key> 鉴权（在控制台「API Key」页创建，形如 hk_xxx），按工作空间隔离并限流。返回统一信封：成功返回数据对象，失败返回 { "error": { "message": "..." } }。

客户端 Clients

客户端（设备/App/网页）的管理与连接 Token 签发。完整模型见 客户端与接入模型。

GET /api/v1/clients — 列出客户端，支持 room / kind / status 筛选。

POST /api/v1/clients — 创建/登记客户端。Body：{clientId, name?, kind?, room?}。

GET /api/v1/clients/{id} — 详情（含在线状态）。

PATCH /api/v1/clients/{id} — 改名 / 设置房间（设置房间 = 实时切房）。Body：{name?, room?, kind?}。

DELETE /api/v1/clients/{id} — 删除。

POST /api/v1/clients/{id}/token：为该客户端签发客户端 Token（连接 MQTT、WSS 或 WebRTC（实验）用）。Body：{ttlSeconds?}，省略表示长期。返回 {token, clientId, expiresAt}。

POST /api/v1/clients/ephemeral — 一步创建临时客户端 + 绑房间 + 返回 Token（网页/App 一步直连）。Body：{room, kind?, ttlSeconds?}，ttlSeconds 默认 3600。返回 {token, clientId, room, expiresAt}。

# 为设备签发一个 30 天的客户端 Token
curl -X POST https://hearo.apps.aisp24.com/api/v1/clients/<id>/token \
  -H "Authorization: Bearer $HEARO_API_KEY" -H "Content-Type: application/json" \
  -d '{"ttlSeconds":2592000}'
# -> { "token": "...", "clientId": "...", "expiresAt": "..." }

智能体 Agents

POST /api/v1/agents — 把「智能体管理」里保存的智能体调度进房间（按工作空间鉴权）。Body：{ room, presetId?, overrides? }（省略 presetId 用平台默认配置），返回 { agentId, room, identity }（201）。

DELETE /api/v1/agents/{agentId} — 停止该智能体（只能停本工作空间房间里的智能体）。返回 { agentId, stopped: true }。

Provider 密钥服务端解析下发，调用方不接触。详见 AI 智能体。

用量 Usage

GET /api/v1/usage — 按天计量，返回最近 90 天记录与合计 {records, totals:{minutes,sessions}}。AI 智能体作为参与者不计入计费时长。