通过 API 批量添加

业务系统持续产生待采集链接时，可以用 API 复用配置、提交新任务。只需手动粘贴链接时，直接使用批量添加即可。任务由采集人的浏览器插件执行。

查看完整 API 参考

适用前提

提交批量任务需要团队版、团队写入权限及可用的采集席位。先手动跑通相同配置，并确认采集人启用最新版插件、已登录来源网站。全部离线时任务会等待；登录过期或验证码需在对应浏览器处理。

获取 API Key 与 App ID

在目标团队的设置 → API复制 API Key 和 App ID。密钥保存在自己的服务端，不放进网页或小程序客户端。先换取短期 token：

curl -X POST 'https://api.scoutary.ai/api/open-auth/token' \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"YOUR_API_KEY","appId":"YOUR_APP_ID","scope":["open-scout:bulk-add"]}'

读取返回的 data.accessToken，后续请求通过 Authorization: Bearer 使用它，并保持 App ID 一致。开发或测试环境使用其 API 设置页与配置面板提供的服务地址。

导出可复用配置

在批量添加完成链接、配方和业务配置。采集到数据集时，先选择保存好的写入规则。

1. 在确认步骤选择“通过API添加相同配置的采集任务”。

2. 在“获取 API 配置”面板复制模板，保存为 task.json。 导出本身不会创建任务，也不会包含 API Key、Cookie 或配方实现。

每个新批次只需填写 urls 并生成新的 requestKey。urls 每项放一个完整 HTTP(S) 地址，单批最多 500 条，不接受混合分享文本。保留导出的配方 key、规则及其他配置；不同配方或写入规则分别提交。

提交并查看进度

Watch、Discover 和 Extract 都使用同一个提交入口：

curl -X POST 'https://api.scoutary.ai/api/open/scout/bulk-add/create?appId=YOUR_APP_ID' \
  -H 'Authorization: Bearer YOUR_SHORT_LIVED_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-binary @task.json

新模板使用 templateVersion: 2。公共参数是 requestKey、urls 和可选的 collectorUserIds，业务配置保存在 config 中。

Watch / Discover：保留导出的 config.kind、recipeKey 和 options。所选配方缺少 key 时，打开 API 配置才按需准备；等待完整 JSON 显示后复制，失败时可重试。普通保存和采集不分配 key。
如需指定精确版本，使用 config.recipeId 替代 recipeKey；无需填写 revision，显式填写时须与该 ID 一致。同时提供 ID 和 key 时，可用 ID 优先；只有 ID 不存在或已 retired 才允许按请求中的 key 兜底，权限、输入及版本校验错误不会换配方。
Extract：config 只包含 kind: "extract"、ruleId 和 configVersion。服务端从保存的写入规则取得目标数据集及精确来源配方，无需重复填写。规则改变后需重新导出配置。配方 key 移到新版不会修改规则；升级来源仍须复核字段映射并显式保存。

仅带 key 的新任务在受理时解析当前绑定。同一 requestKey 与完全相同正文重放、等待及失败项重试，继续使用已受理的配方和规则快照。新任务使用新 requestKey，才重新解析当前绑定；调用方无需查询替代配方 ID。

三类任务都返回批次 ID data.id 和进度页 data.progressUrl；Extract 额外返回目标 data.datasetId。创建数据集、配置字段映射仍在界面中完成。

HTTP 202 仅表示已受理，不代表采集或写入完成。 保存返回的 data.progressUrl，在自己的系统提供“查看采集进度”链接。进度页可查看每条链接的结果和失败原因。

重试与恢复

情况	处理方式
未收到提交响应	用同一个 `requestKey` 和完全相同的正文重试，避免重复创建；同一键配不同正文会返回 409。
提交新的一批链接	使用新的 `requestKey`；超过 500 条时拆批。
离线、登录过期或验证码	在采集人浏览器中处理，再回到进度页按提示恢复或重试。
配方、规则或目标配置变化	核对后重新导出配置。
权限或额度不足	恢复团队权限、席位或额度，再按进度页提示处理。
返回 429	按 `Retry-After` 指定的秒数等待后重试。

完整请求字段、响应结构和错误码见上方 API 参考。