# REST API

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

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

> ℹ️ **本部署基址**：`https://hearo.apps.aisp24.com`——下文的 `$BASE` 即它。例：`https://hearo.apps.aisp24.com/api/v1/clients`。

## 客户端 Clients

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

`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}`。

```bash
# 为设备签发一个 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 智能体](/docs/agents)。

## 用量 Usage

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

> 💡 **典型集成**：你的后端用 API Key 调 `POST /api/v1/clients/{id}/token`（或 `:ephemeral`）为客户端签发 Token，下发给设备/网页，客户端再用它走默认的 [WebSocket](/docs/websocket)、[WebRTC（实验）](/docs/webrtc) 或 MQTT 连接，房间由 client→room 映射决定。