使用 rrweb Cloud API 可以摄取 rrweb 事件、查找录制、获取回放数据以及渲染托管预览。先确定你需要完成的任务，然后使用链接指向的生成操作页面查看完整的请求与响应模式（schema）。
Servers
基础 URL 与格式
生产环境请求使用 https://api.rrweb.com。
- HTTP API 密钥通过
Authorization: Bearer <key>发送。 - JSON 端点返回
application/json。 - HTTP 事件摄取接受
application/json、application/x-ndjson或application/ndjson。 - 托管播放器返回
text/html；截图根据请求返回image/png、image/jpeg或image/webp。
选择凭据
浏览器摄取请使用公开写入密钥，只在受信服务器上使用私有 API 密钥以获得完整的读写权限，不受信任的查看者需要临时读取权限时则使用预签名 URL/令牌。
| 凭据 | 允许运行的位置 | 能力 |
|---|---|---|
公开写入密钥（public_key_rr_*） | 浏览器或服务器 | 创建录制、摄取事件以及附加浏览器可见的元数据 |
私有 API 密钥（secret_key_rr_*） | 仅限受信服务器 | 完整的读写权限，包括摄取、元数据、检索以及预签名访问 |
| 预签名 URL/令牌 | 针对单个限定资源的不受信任的查看者 | 在过期时间之前读取已签名的录制资源 |
公开写入密钥本身设计为浏览器可见，是浏览器摄取推荐使用的凭据。私有 API 密钥拥有完整的读写权限，是仅供受信服务器使用的服务器机密。由于其更大的影响范围，严格的存储与轮换尤为重要：绝不可在浏览器代码中暴露私有 API 密钥。 对于不受信任的查看者，请改用限定范围的预签名 URL/令牌。
按使用意图开始
采集录制事件
使用公开写入密钥调用创建录制事件端点，为一个 UUID 录制 ID 发送 rrweb 事件。
curl --request POST \
--url 'https://api.rrweb.com/recordings/550e8400-e29b-41d4-a716-446655440000/events' \
--header 'Authorization: Bearer public_key_rr_your_key' \
--header 'Content-Type: application/json' \
--data '[{"type":1,"timestamp":1714857600000,"data":{}}]'如需持续的浏览器采集，推荐使用浏览器客户端，它默认使用 WebSocket 摄取。
列出并搜索录制
使用私有 API 密钥调用列出录制端点，并以 AND 逻辑组合 metadata[key]=value 过滤器。
curl --get \
--url 'https://api.rrweb.com/recordings' \
--header 'Authorization: Bearer secret_key_rr_your_key' \
--data-urlencode 'metadata[userId]=user-123' \
--data-urlencode 'limit=50' \
--data-urlencode 'offset=0'获取回放事件
使用私有 API 密钥调用获取录制事件。
curl --request GET \
--url 'https://api.rrweb.com/recordings/550e8400-e29b-41d4-a716-446655440000/events' \
--header 'Authorization: Bearer secret_key_rr_your_key' \
--header 'Accept: application/json'如需将由元数据选出的多个录制合并为一条可回放的流，请使用合成回放。
渲染播放器或截图
使用私有 API 密钥调用获取录制播放器或获取录制截图端点，并在受信任的服务器上为浏览器查看者生成预签名链接，而不是将私有密钥发送到浏览器。
curl --request GET \
--url 'https://api.rrweb.com/recordings/550e8400-e29b-41d4-a716-446655440000/player' \
--header 'Authorization: Bearer secret_key_rr_your_key' \
--header 'Accept: text/html' \
--output recording-player.htmlcurl --request GET \
--url 'https://api.rrweb.com/recordings/550e8400-e29b-41d4-a716-446655440000/screenshot.png?time=offset%3A0' \
--header 'Authorization: Bearer secret_key_rr_your_key' \
--header 'Accept: image/png' \
--output recording.png获取录制统计
使用私有 API 密钥调用获取录制统计信息端点。
curl --request GET \
--url 'https://api.rrweb.com/statistics' \
--header 'Authorization: Bearer secret_key_rr_your_key' \
--header 'Accept: application/json'分页
列出录制与列出回放使用 offset 分页。limit 默认为 50，可接受 1–100 条结果；offset 默认为 0。响应中不包含游标（cursor），因此在获取下一页时请自行保留当前 offset。
获取预签名查看访问
在受信服务器上，对使用私有 API 密钥发起的受支持的列表或录制详情请求设置 includeSignedUrls=true。响应随后可以包含限定在录制或回放资源及其过期时间范围内的链接。只将返回的预签名 URL/令牌传给不受信任的查看者；不要把私有密钥复制到客户端代码中。
错误
错误响应体并不统一。应用错误与身份验证失败通常返回纯文本，而请求模式校验可能返回 JSON。请同时根据状态码和 Content-Type 进行分支判断，并参考各生成操作页面获取特定端点的响应：
| 状态码 | 含义 |
|---|---|
| 400 | 请求错误或参数无效 |
| 401 | 身份验证缺失、无效或缺少所需的权限范围 |
| 403 | 预签名 URL 已过期或签名无效 |
| 404 | 按文档所述，未找到请求的录制或回放资源 |
| 422 | 截图位置超出录制范围 |
| 500 | 内部服务器错误 |
| 502 | 上游操作失败 |
版本控制
OpenAPI 文档会报告当前的 API 版本。在依赖兼容性别名或修改集成之前，请阅读 API 版本控制与兼容性。