文档 / API
REST API 参考
每个接口都位于 /api/v1 路径下,并使用来自 控制台 → 集成的 API 密钥进行身份验证。密钥仅显示一次,可以设置为只读或读写;已撤销的密钥会立即停止工作。
请以 Authorization: Bearer bfk_…的形式发送密钥。错误会以 Problem Details JSON 格式返回,并附带一个 code 字段,您可以据此进行分支处理。
GET
/api/v1/me作用域:read查询某个密钥所属的工作区和套餐。这是检查密钥是否可用的简便方法。
curl -H "Authorization: Bearer bfk_…" \ https://your-domain/api/v1/me
GET
/api/v1/bots?page=1&pageSize=50作用域:read列出工作区的机器人及其状态和版本。
GET
/api/v1/bots/{botId}作用域:read单个机器人的信息:状态、时区、版本、最近一次错误。
GET
/api/v1/bots/{botId}/subscribers?q=&page=1&pageSize=50作用域:read机器人的受众列表,可按姓名或用户名搜索。
GET
/api/v1/bots/{botId}/logs?level=error&limit=50作用域:read最近的运行时日志;可按级别筛选。
GET
/api/v1/bots/{botId}/analytics?days=30作用域:read按天统计的消息量、投递失败数和订阅者增长情况。
GET
/api/v1/bots/{botId}/broadcasts作用域:read该机器人的群发历史记录。
GET
/api/v1/bots/{botId}/logs/stream作用域:read以服务器发送事件(SSE)形式提供的实时日志。条目以 LogEntry JSON 的 data: 行形式到达;每 15 秒发送一次保活注释;服务器会在 10 分钟后关闭会话(需重新连接)。EventSource 无法发送请求头,因此请使用基于 fetch 的流式处理来消费数据。
curl -N -H "Authorization: Bearer bfk_…" https://your-domain/api/v1/bots/{botId}/logs/streamPOST
/api/v1/bots/{botId}/broadcasts作用域:write通过一次调用创建并将群发加入队列。请求体:{ "name": "…", "text": "…", "segmentId": "…"(可选) }。投递会经过与控制台群发相同的节流管道;您的套餐限额将适用。
curl -X POST -H "Authorization: Bearer bfk_…" \
-H "Content-Type: application/json" \
-d '{"name":"June promo","text":"20% off until Friday"}' \
https://your-domain/api/v1/bots/{botId}/broadcasts状态码与限制
- 401 UNAUTHENTICATED ——密钥缺失或无效。
- 403 FORBIDDEN ——该密钥缺少写入作用域。
- 403 PLAN_LIMIT ——已达到群发配额;错误消息中会说明上限。
- 404 NOT_FOUND ——ID 错误,或该机器人属于另一个工作区。
- 分页大小上限为 100;日志条数上限为 200。