开发者接入

OpenAPI：GET /api/v1/openapi.json。服务器端请求使用 X-API-Key，密钥继承账号所在工作空间的角色，不赋予空间外访问权。Viewer 可读不可写，访客删除还要求 Owner/Admin。每来源 IP 每分钟 60 次。不要把 API Key 放在浏览器、安装脚本或公开源码中。

基础地址：/api/v1/workspaces/{workspaceId}。

路径	方法	用途
/apps	GET	最多 1000 个应用
/apps/{appId}/search-console	GET	独立的 Google 搜索报告与日期范围
/apps/{appId}/releases	GET / POST	最新 100 个版本、记录版本及上传 Source Map
/apps/{appId}/events	GET	分页导出有稳定事件 ID 的事件
/apps/{appId}/visitor-erasures	GET / POST	删除任务状态、提交明确确认的删除请求

导出需 startMs、endMs（已过去的毫秒时间戳，跨度最多 31 天），limit 为 1–500。后续页沿用同一时间范围，把响应 nextCursor 原样作为 cursor；空字符串结束。旧 SDK 没有事件 ID 的记录不支持该增量接口，响应明确标注。实时队列的迟到事件可能改变已读取的范围；仓库同步应重读重叠窗口（例如 10 分钟），按 (appId, id) 去重。事件时间上界不是数据库快照，不能承诺一遍分页能包含所有迟到事件。大历史回填分日执行。

发布记录 POST 示例：

{"version":"2026.10.11","deployedMs":1791712800000,"notes":"Checkout fix","artifact":"/assets/app.js","map":"{\"version\":3,...}"}

版本最长 100 字符、备注 1000 字节、Source Map 最大 2 MB；每应用最多 100 份、累计 20 MB。单份最多 10000 个源文件、20000 个名称、50000 个映射段，超出需按构建产物拆分。版本和脚本路径精确对应 SDK 的 release 与错误文件；支持普通 v3 map，indexed map 需先由构建工具展平。sourcesContent 丢弃，Source Map 不公开下载。浏览器错误的列号是 1 开始，映射库采用 0 开始，服务端负责转换。CI 上传与控制台上传使用同一验证和空间权限。

事件 Webhook

网站设置可添加至多 3 个 HTTPS 公网接收端，自选 event/error/pageview/identify/webvital。签名密钥仅创建时显示一次，服务端加密保存。通知概要包含事件 ID、应用 ID、类型、事件名称、事件时间、页面路径和版本；不包含访客 ID、IP、完整 URL、请求体或业务属性。事件名称与路径可能仍包含业务信息，应依据业务定义配置。

接收端校验 X-AntDock-Timestamp（Unix 秒）与 X-AntDock-Signature：

v1=hex(HMAC-SHA256(secret, timestamp + "." + raw_request_body))

比较签名需用恒定时间方法，并拒绝超出合理时钟窗口（例如 5 分钟）的请求。按 Idempotency-Key 去重，成功返回 2xx。发送是至少一次：服务端崩溃或连接断开可能重发。总计最多 6 次尝试，按 1/2/4/8/16 分钟退避；签名时间每次重试重新生成。跳转不跟随，私网、保留地址和 DNS 重绑定被拒绝。接收端暂停、应用删除/停用、访客删除都会停止对应待发数据；已送达的外部副本需由接收端自己删除。

每接收端最多 10000 条待发记录；队列满时跳过新 Webhook，并在控制台显示累计跳过数，统计采集继续运行。投递概要和去重记录保留；90 天后记录从产品中隐藏，原始内容仍由系统管理员保管。Webhook 用于业务自动化概要，完整数据仓库使用导出接口。

API Key 与控制台登录

API Key 仅可用于 /api/v1 公开 API；/api/trpc 和其他控制台接口需要正常登录会话。API Key 不能创建其他 Key、修改账号安全设置、通知渠道或成员。已使用 Key 调用控制台接口的脚本应迁移到公开 API。

访客删除按工作空间每分钟最多 10 个新请求、同时最多 50 个待处理请求。重复的待删除访客返回已有任务。后台合并同站点请求，写入可逆的隐藏范围，不提交 ClickHouse 删除任务。完成表示对应访客、会话、用户的数据已从查询、统计、导出和回放中隐藏，并阻止新采集；原始记录和文件保留。页面和公开 API 不提供恢复功能，仅系统管理员可通过服务器恢复工具按批次恢复。此接口不是物理清除个人数据的接口。

服务器访问日志使用 POST /api/v1/workspaces/:workspaceId/requests，请求体契约为 {appId, requests}（见采集文档）。旧 /api/collect/requests 保留登录会话路径，API Key 客户端应迁到新版公开 API。