使用 NestBrowser 的 REST API 和 ChromeDriver 兼容接口，通过 Selenium、Puppeteer、Playwright 或任意自动化框架控制浏览器环境。

NestBrowser 本地三方 API 文档

本文面向三方系统、本机脚本、MCP/Agent 和 SaaS 集成调用方，说明 NestBrowser 本地 HTTP API 的公开使用方式。

本地 API 默认只绑定在本机地址，适合由同一台机器上的可信客户端调用。不要把端口暴露到公网或不可信局域网。

如果你是第一次接入，建议按这个顺序阅读和调试：

先调用 /status，确认本机服务已经启动、端口正确。
再调用账号或分组接口，确认你能拿到环境 ID 或 UUID。
如果只是打开浏览器，用 /api/v1/browser/start。
如果要执行浏览器 RPA，用 Platform RPA 的 /api/v1/platform-rpa/runs，不要使用旧的浏览器 RPA 接口。
如果要执行云手机 RPA，用 /api/v1/cloud-mobile/rpa 或 /api/v2/cloud-mobile/rpa。

这份文档只描述推荐给三方使用的接口。应用内部还有一些旧页面、调试、缓存、私有 Socket.IO 相关路由，不作为三方集成契约。

快速开始

Base URL

http://127.0.0.1:43820 | http://local.nestbrowser.com:43820

HTTP 服务默认端口为 43820。如果端口被占用，应用会自动递增端口，例如 43821、43822。应用内页面会读取实际端口；外部调用方可通过当前配置或健康检查确认服务是否可用。

首次接入时最常见的问题是“请求一直连不上”。这通常不是鉴权问题，而是端口不对、NestBrowser 没启动，或调用方不在同一台机器上。先在运行 NestBrowser 的电脑上执行健康检查；如果 /status 不通，其他接口也不会通。

健康检查

curl "http://127.0.0.1:43820/status"

成功响应：

{
  "code": 200,
  "msg": "success",
  "data": {
    "status": "ok",
    "service": "nestbrowser-local-api",
    "api_version": "v1",
    "version": "3.5.2",
    "server_time": "2026-06-15T08:00:00.000Z",
    "matched": false,
    "mcp_entitlement": {
      "enabled": true
    }
  }
}

安全边界

当前本地 HTTP 服务没有统一的 Authorization、X-API-Key 或签名校验中间件。接口主要依赖本机访问边界保护。

项目	说明
监听地址	默认 `127.0.0.1`
请求格式	除特别说明外，使用 `Content-Type: application/json`
认证方式	当前版本本地服务不校验 API Key
调用边界	仅允许可信本机进程调用
并发建议	打开浏览器、RPA、云手机任务应低并发提交

如果你在三方系统里看到“鉴权失败”，通常不是本地 HTTP 服务返回的统一鉴权错误，而可能来自这些场景：

现象	常见原因	处理方式
HTTP 401/403	请求打到了云端服务或代理，不是本地 HTTP 服务	确认 URL 是 `127.0.0.1:<port>`
HTTP 404	路径写错、方法写错，或端口不是 HTTP 服务端口	对照接口总览检查 Method 和 Path
`code: -1` 且提示权限/购买/登录	业务层要求当前 NestBrowser 登录态、模板购买状态或功能权限	在 NestBrowser 客户端内确认账号登录、模板可用
浏览器或 RPA 没执行	提交成功只代表任务被接受，后续执行异步发生	继续查 run 详情、events 或云手机状态接口

响应格式

多数公开接口返回以下结构：

{
  "code": 0,
  "msg": "success",
  "data": {}
}

部分本地资源接口沿用历史响应：

{
  "success": true,
  "code": 200,
  "msg": "ok",
  "data": []
}

失败响应通常为：

{
  "code": -1,
  "msg": "failed",
  "data": {}
}

注意：历史接口里 code 的含义不完全统一。一般可以按下面规则处理：

判断方式	说明
`code === 0`	常见成功响应
`code === 200` 且 `msg === "success"` 或 `success === true`	旧接口或健康检查成功响应
`code === -1`	业务失败，优先读取 `msg`
HTTP 状态不是 2xx	路由、端口、服务异常或请求方法错误

分页参数

部分列表接口支持普通分页：

参数	类型	默认值	说明
`limit`	number	`50` 或接口默认值	返回数量上限
`offset`	number	`0`	偏移量
`status`	string	无	可选状态过滤
`category`	string	无	可选分类过滤

部分后台列表兼容 React Admin 查询格式：

参数	类型	示例
`range`	JSON string	`[0,19]`
`sort`	JSON string	`["id","DESC"]`
`filter`	JSON string	`{"status":"success"}`

range、sort、filter 看起来像对象或数组，但请求时必须是 URL Query 字符串。也就是说，浏览器或 curl 里需要 URL 编码：

curl "http://127.0.0.1:43820/api/v1/local-envs?range=[0,19]&sort=[%22id%22,%22ASC%22]&filter={}"

如果你传的是未编码 JSON，部分 HTTP 客户端会自动处理，部分客户端会把引号、空格或大括号截断，导致服务端解析不到过滤条件。

异步任务约定

浏览器环境打开、Platform RPA、云手机 RPA 都可能异步执行。提交接口返回成功只表示任务已被接受或开始处理，调用方应继续查询详情、事件或状态接口。

可以把这些接口理解为“下发任务”而不是“同步拿最终结果”。例如 /api/v1/platform-rpa/runs 返回成功后，浏览器可能还在启动、脚本可能还在执行。调用方应保存返回的 run_id，再轮询 /api/v1/platform-rpa/runs/:runId 和 /api/v1/platform-rpa/runs/:runId/events。

关键名词

名词	通俗解释
环境 ID / `id` / `serial_number`	浏览器环境的数字 ID，常用于接口查询和打开环境
UUID / `uuid` / `user_id`	浏览器环境的唯一字符串 ID，兼容 AdsPower 风格字段
分组 ID / `group_id`	一组浏览器环境的 ID，RPA 可以按分组批量选择环境
远程模板	NestBrowser 服务端提供的浏览器 RPA 模板
本地脚本	导入或在本机生成的 Platform RPA 脚本
运行方案	一套保存好的 RPA 运行配置，方便复用
参数模板	一套保存好的脚本参数，计划任务可以轮换或消耗使用
计划任务	到点后自动用某个运行方案创建 RPA run

接口总览

分组	方法	路径	用途
系统	`GET`	`/status`	健康检查和版本信息
账号	`POST`	`/api/v1/user/create`	创建环境账号
账号	`POST`	`/api/v1/user/update`	更新环境参数
账号	`GET`	`/api/v1/user/list`	查询环境账号列表
账号	`POST`	`/api/v1/user/delete`	删除环境账号
账号	`POST`	`/api/v1/user/regroup`	移动浏览器环境账号分组
分组	`POST`	`/api/v1/group/create`	创建分组
分组	`POST`	`/api/v1/group/update`	更新分组
分组	`GET`	`/api/v1/group/list`	查询分组
浏览器	`GET`	`/api/v1/browser/start`	按 Query 打开环境
浏览器	`POST`	`/api/v1/browser/start`	按 Body 打开环境
浏览器	`GET`	`/api/v1/browser/stop`	关闭环境
浏览器	`GET`	`/api/v1/browser/active`	查询环境运行状态
云手机	`POST`	`/api/v1/cloud-mobile/rpa`	提交云手机 RPA
云手机	`POST`	`/api/v2/cloud-mobile/rpa`	提交云手机 RPA v2
云手机	`POST`	`/api/v1/cloud-mobile/schedule`	创建云手机循环调度
云手机	`GET`	`/api/v1/local-envs`	查询本地云手机环境
云手机	`GET`	`/api/v1/local-ips`	查询本地云手机 IP
云手机	`GET`	`/api/v1/task-polling/status`	查询任务轮询状态
云手机	`GET`	`/api/v1/schedule/status`	查询云手机调度状态
Platform RPA	`GET`	`/api/v1/platform-rpa/templates`	查询远程模板
Platform RPA	`GET`	`/api/v1/platform-rpa/templates/:templateId/meta`	查询模板详情和参数
Platform RPA	`GET`	`/api/v1/platform-rpa/templates/:templateId/cache`	查询模板缓存
Platform RPA	`POST`	`/api/v1/platform-rpa/templates/:templateId/cache/refresh`	刷新模板缓存
Platform RPA	`GET`	`/api/v1/platform-rpa/template-favorites`	查询收藏模板
Platform RPA	`POST`	`/api/v1/platform-rpa/template-favorites/:templateId`	收藏模板
Platform RPA	`DELETE`	`/api/v1/platform-rpa/template-favorites/:templateId`	取消收藏
Platform RPA	`GET`	`/api/v1/platform-rpa/template-favorites/:templateId/status`	查询模板可运行状态
Platform RPA	`GET`	`/api/v1/platform-rpa/local-scripts`	查询本地脚本
Platform RPA	`POST`	`/api/v1/platform-rpa/local-scripts/import`	导入本地脚本
Platform RPA	`POST`	`/api/v1/platform-rpa/local-scripts/check`	校验脚本草稿
Platform RPA	`POST`	`/api/v1/platform-rpa/local-scripts/generate`	生成脚本草稿
Platform RPA	`POST`	`/api/v1/platform-rpa/local-scripts/generate/stream`	流式生成脚本草稿
Platform RPA	`POST`	`/api/v1/platform-rpa/local-scripts/save`	保存脚本草稿
Platform RPA	`POST`	`/api/v1/platform-rpa/local-scripts/run-from-prompt`	按提示词生成并运行
Platform RPA	`GET`	`/api/v1/platform-rpa/local-scripts/:localScriptId`	查询本地脚本详情
Platform RPA	`GET`	`/api/v1/platform-rpa/local-scripts/:localScriptId/run-summaries`	查询脚本运行摘要
Platform RPA	`DELETE`	`/api/v1/platform-rpa/local-scripts/:localScriptId`	删除本地脚本
Platform RPA	`POST`	`/api/v1/platform-rpa/runs`	创建 RPA 运行
Platform RPA	`GET`	`/api/v1/platform-rpa/runs`	查询运行列表
Platform RPA	`GET`	`/api/v1/platform-rpa/runs/:runId`	查询运行详情
Platform RPA	`GET`	`/api/v1/platform-rpa/runs/:runId/events`	查询运行事件
Platform RPA	`GET`	`/api/v1/platform-rpa/runs/:runId/artifacts/open`	读取运行产物
Platform RPA	`DELETE`	`/api/v1/platform-rpa/runs/:runId`	删除运行记录
Platform RPA	`GET`	`/api/v1/platform-rpa/run-profiles`	查询运行方案
Platform RPA	`POST`	`/api/v1/platform-rpa/run-profiles`	创建运行方案
Platform RPA	`GET`	`/api/v1/platform-rpa/run-profiles/:id`	查询运行方案详情
Platform RPA	`PUT`	`/api/v1/platform-rpa/run-profiles/:id`	更新运行方案
Platform RPA	`POST`	`/api/v1/platform-rpa/run-profiles/:id/touch`	更新最近使用时间
Platform RPA	`DELETE`	`/api/v1/platform-rpa/run-profiles/:id`	删除运行方案
Platform RPA	`GET`	`/api/v1/platform-rpa/param-templates`	查询参数模板
Platform RPA	`POST`	`/api/v1/platform-rpa/param-templates`	创建参数模板
Platform RPA	`GET`	`/api/v1/platform-rpa/param-templates/:id`	查询参数模板详情
Platform RPA	`PUT`	`/api/v1/platform-rpa/param-templates/:id`	更新参数模板
Platform RPA	`DELETE`	`/api/v1/platform-rpa/param-templates/:id`	删除参数模板
Platform RPA	`GET`	`/api/v1/platform-rpa/schedules`	查询计划任务
Platform RPA	`GET`	`/api/v1/platform-rpa/schedules/stats`	查询计划任务统计
Platform RPA	`POST`	`/api/v1/platform-rpa/schedules`	创建计划任务
Platform RPA	`GET`	`/api/v1/platform-rpa/schedules/:id`	查询计划任务详情
Platform RPA	`PUT`	`/api/v1/platform-rpa/schedules/:id`	更新计划任务
Platform RPA	`POST`	`/api/v1/platform-rpa/schedules/:id/toggle`	启停计划任务
Platform RPA	`POST`	`/api/v1/platform-rpa/schedules/:id/run-now`	立即运行计划任务
Platform RPA	`GET`	`/api/v1/platform-rpa/schedules/:id/fires`	查询触发记录
Platform RPA	`DELETE`	`/api/v1/platform-rpa/schedules/:id`	删除计划任务

系统状态

GET /status

获取本地服务状态、应用版本和可选账号匹配信息。

这个接口适合放在接入流程的第一步。它不打开浏览器、不执行任务，只用来确认“本地 API 服务是否可用”。如果这个接口不通，优先检查 NestBrowser 是否已经启动、端口是否正确、调用方是否和 NestBrowser 在同一台机器。

Query 参数：

参数	类型	必填	说明
`username`	string	否	可选诊断字段；返回 `matched`，不作为认证或权限判断

请求示例：

curl "http://127.0.0.1:43820/status"

响应示例见“快速开始”。

字段说明：

字段	说明
`data.status`	`ok` 表示本地 API 服务正在响应
`data.version`	当前 NestBrowser 客户端版本
`data.matched`	仅在传 `username` 时有诊断意义，表示本地是否匹配到用户信息
`data.mcp_entitlement`	MCP 相关权益信息；不影响普通健康检查

账号与分组

账号与分组接口兼容 AdsPower 风格字段，并会映射为 NestBrowser 本地账号模型。

第一次接入时，通常需要先创建或查询账号，再用账号 ID 打开浏览器环境。这里有两套命名需要注意：

NestBrowser 含义	接口字段	说明
账号数字 ID	`id` / `serial_number`	最常用于 `/browser/start?ids=...`
账号 UUID	`uuid` / `user_id`	字符串唯一标识，兼容 AdsPower 风格
分组 ID	`group_id`	用于批量移动账号或按分组运行任务

如果你不确定该传 ID 还是 UUID，优先使用数字 ID，也就是 serial_number 或 ids。如果你的系统已经保存了 user_id，也可以用 UUID 方式调用。

POST /api/v1/user/create

创建账号并生成浏览器指纹。

这个接口会创建一个可打开的浏览器环境。username 是兼容字段，不一定必须是邮箱；如果传了 domain_name，系统会按这个域名推断平台信息。没有传 name 时，会使用默认名称。

Body 参数：

参数	类型	必填	说明
`username`	string	否	兼容字段，会映射为账号
`name`	string	否	账号名称；为空时使用默认名称
`domain_name`	string	否	平台域名
`group_id`	number	否	分组 ID
`core_version`	number	否	浏览器核心版本
`proxy`	object/string	否	代理配置，按账号模型透传

请求示例：

curl -X POST "http://127.0.0.1:43820/api/v1/user/create" \
  -H "Content-Type: application/json" \
  -d '{"username":"demo@example.com","name":"Demo","domain_name":"example.com"}'

成功响应：

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 123,
    "user_id": "env-uuid",
    "serial_number": 123
  }
}

POST /api/v1/user/update

更新账号。

更新时必须传 serial_number，它就是创建或列表接口返回的账号数字 ID。只传需要修改的字段即可，避免把未知字段覆盖为空。

Body 参数：

参数	类型	必填	说明
`serial_number`	number	是	账号 ID
`username`	string	否	兼容字段，会映射为账号
其他字段	any	否	按账号模型透传更新

curl -X POST "http://127.0.0.1:43820/api/v1/user/update" \
  -H "Content-Type: application/json" \
  -d '{"serial_number":123,"name":"Updated Demo"}'

GET /api/v1/user/list

分页查询账号。

这个接口常用于拿到后续打开浏览器所需的 serial_number 或 user_id。返回列表会把部分内部字段隐藏，并转换为兼容字段。

Query 参数：

参数	类型	默认值	说明
`page`	number	`1`	页码
`page_size`	number	`10`	每页数量
`serial_number`	number	无	按账号 ID 查询
`user_id`	string	无	按账号 UUID 查询
`group_id`	number	无	按分组查询

curl "http://127.0.0.1:43820/api/v1/user/list?page=1&page_size=20"

POST /api/v1/user/delete

批量删除账号。

删除账号会清理对应本地数据，调用前请确认这些账号没有正在运行的浏览器窗口或 RPA 任务。

Body 参数：

参数	类型	必填	说明
`serial_numbers`	number[]	二选一	账号 ID 列表
`user_ids`	string[]	二选一	账号 UUID 列表

curl -X POST "http://127.0.0.1:43820/api/v1/user/delete" \
  -H "Content-Type: application/json" \
  -d '{"serial_numbers":[123,124]}'

POST /api/v1/user/regroup

批量移动账号分组。

Body 参数：

参数	类型	必填	说明
`user_ids`	number[]	是	账号 ID 列表
`group_id`	number	是	目标分组 ID

curl -X POST "http://127.0.0.1:43820/api/v1/user/regroup" \
  -H "Content-Type: application/json" \
  -d '{"user_ids":[123],"group_id":2}'

POST /api/v1/group/create

创建账号分组。

Body 参数：

参数	类型	必填	说明
`group_name`	string	是	分组名称

curl -X POST "http://127.0.0.1:43820/api/v1/group/create" \
  -H "Content-Type: application/json" \
  -d '{"group_name":"Demo Group"}'

POST /api/v1/group/update

更新账号分组。

Body 参数：

参数	类型	必填	说明
`group_id`	number	是	分组 ID
`group_name`	string	是	分组名称

curl -X POST "http://127.0.0.1:43820/api/v1/group/update" \
  -H "Content-Type: application/json" \
  -d '{"group_id":2,"group_name":"New Name"}'

GET /api/v1/group/list

查询账号分组。

Query 参数：

参数	类型	默认值	说明
`page`	number	`1`	页码
`page_size`	number	`10`	每页数量
`group_name`	string	无	分组名过滤

curl "http://127.0.0.1:43820/api/v1/group/list?page=1&page_size=20"

浏览器环境

浏览器环境接口用于打开、关闭和查询环境。浏览器 RPA 执行请使用 Platform RPA。

浏览器环境接口只负责“打开窗口、关闭窗口、查询窗口”。如果你的目标是让浏览器自动执行脚本，请跳到 Platform RPA 章节。旧的 /api/v1/browser/rpa 不再作为推荐接口。

打开环境前，你需要先知道环境的数字 ID 或 UUID。最常见流程是：

调用 /api/v1/user/list 找到账号。
取返回里的 serial_number。
调用 /api/v1/browser/start?ids=<serial_number>。
如果需要连接 CDP、Puppeteer 或 Selenium，读取响应里的 debug_port 或 ws。

GET /api/v1/browser/start

使用 Query 参数打开浏览器环境。该接口兼容 user_id、serial_number 字段。

GET 方式适合简单调试或兼容已有系统。多个环境可以用逗号分隔，例如 ids=101,102,103。

Query 参数：

参数	类型	必填	说明
`ids`	string	二选一	账号 ID，多个用逗号分隔
`uuids`	string	二选一	账号 UUID，多个用逗号分隔
`serial_number`	string	否	兼容字段，等同 `ids`
`user_id`	string	否	兼容字段，等同 `uuids`
`system_os`	string	否	覆盖系统指纹，多个用逗号分隔

curl "http://127.0.0.1:43820/api/v1/browser/start?ids=123"

POST /api/v1/browser/start

使用 JSON Body 打开浏览器环境。

POST 方式更适合正式接入，因为数组、代理覆盖、系统指纹覆盖等结构化参数更容易表达。

Body 参数：

参数	类型	必填	说明
`ids`	number[]	二选一	账号 ID 列表
`uuids`	string[]	二选一	账号 UUID 列表
`system_os`	string[]	否	覆盖系统指纹
`proxy`	object	否	覆盖代理配置

curl -X POST "http://127.0.0.1:43820/api/v1/browser/start" \
  -H "Content-Type: application/json" \
  -d '{"ids":[123]}'

成功响应中的 data 是打开结果数组，通常包含环境状态、UUID、调试端口、WebDriver 和 CDP 地址。

如果接口返回成功但窗口没有立刻出现，不一定是失败。打开浏览器会经过读取账号、准备环境、等待并发容量、启动进程等步骤。批量打开时尤其要避免高并发反复提交。

GET /api/v1/browser/stop

关闭浏览器环境。

关闭接口同样支持 ID 或 UUID。建议调用方记录自己打开过哪些环境，关闭时只传目标环境，不要把所有账号都传进去。

Query 参数：

参数	类型	必填	说明
`ids`	string	二选一	账号 ID，多个用逗号分隔
`uuids`	string	二选一	账号 UUID，多个用逗号分隔
`serial_number`	string	否	兼容字段，等同 `ids`
`user_id`	string	否	兼容字段，等同 `uuids`

curl "http://127.0.0.1:43820/api/v1/browser/stop?ids=123"

GET /api/v1/browser/active

查询单个浏览器环境运行状态。

这个接口只查询一个环境是否正在运行。它不会启动环境。如果返回失败，常见原因是 ID/UUID 不存在，或该环境当前没有打开。

Query 参数：

参数	类型	必填	说明
`id`	number	二选一	账号 ID
`uuid`	string	二选一	账号 UUID
`serial_number`	number	否	兼容字段，等同 `id`
`user_id`	string	否	兼容字段，等同 `uuid`

curl "http://127.0.0.1:43820/api/v1/browser/active?id=123"

成功响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "Active",
    "uuid": "env-uuid",
    "debug_port": 9222,
    "ws": {
      "url": "ws://127.0.0.1:9222/devtools/browser/...",
      "puppeteer": "ws://127.0.0.1:9222/devtools/browser/...",
      "selenium": "127.0.0.1:9222"
    }
  }
}

云手机

云手机接口用于控制本地或云手机设备执行 RPA、查询本地设备和调度状态。

云手机和浏览器环境是两套能力。浏览器接口控制的是浏览器账号环境；云手机接口控制的是 Android 设备或容器设备。不要把浏览器的 env_ids 直接当成云手机的 envs 使用。

云手机 RPA 的常见流程：

调用 /api/v1/local-envs 查询可用云手机设备。
取设备 UUID，作为 envs 传入。
准备云手机 RPA 脚本 UUID，作为 rpa_uuid。
调用 /api/v2/cloud-mobile/rpa 提交任务。
如果使用队列，调用 /api/v1/task-polling/status 查看轮询状态。

POST /api/v1/cloud-mobile/rpa

提交云手机 RPA 任务。

v1 是较早的云手机 RPA 提交接口，适合已有调用方继续使用。新接入如果需要队列追踪，优先使用 v2。

Body 参数：

参数	类型	必填	说明
`rpa_uuid`	string	是	云手机 RPA 脚本 UUID
`envs`	string[]	是	目标设备 UUID 列表
`variables`	object	否	传入脚本的变量
`taskId`	string	否	调用方任务 ID

curl -X POST "http://127.0.0.1:43820/api/v1/cloud-mobile/rpa" \
  -H "Content-Type: application/json" \
  -d '{"rpa_uuid":"script-uuid","envs":["device-uuid"],"variables":{},"taskId":"task-001"}'

POST /api/v2/cloud-mobile/rpa

提交云手机 RPA v2 任务。v2 会校验参数，并支持通过 queued_count 启动后续队列轮询。

taskId 建议由调用方生成并保持唯一，例如订单号、任务号或 task-${Date.now()}。它不是脚本 ID，而是这次执行任务的追踪 ID。

queued_count 表示当前任务后面还有多少个任务等待执行。如果大于 0，本地服务会把任务加入轮询管理，用于后续队列调度。

Body 参数：

参数	类型	必填	说明
`rpa_uuid`	string	是	云手机 RPA 脚本 UUID
`envs`	string[]	是	目标设备 UUID 列表
`variables`	object	否	传入脚本的变量
`taskId`	string	是	任务 ID，用于队列追踪
`queued_count`	number	否	队列剩余数量，大于 0 时启动轮询

curl -X POST "http://127.0.0.1:43820/api/v2/cloud-mobile/rpa" \
  -H "Content-Type: application/json" \
  -d '{"rpa_uuid":"script-uuid","envs":["device-uuid"],"variables":{},"taskId":"task-001","queued_count":0}'

POST /api/v1/cloud-mobile/schedule

创建云手机循环调度任务。

这个接口是云手机自己的轻量调度，不是 Platform RPA 计划任务。firstExecutionTime 必须是秒级 Unix 时间戳，不是毫秒。如果你传了 JavaScript 的 Date.now()，它是毫秒，需要除以 1000 并取整。

Body 参数：

参数	类型	必填	默认值	说明
`scheduleId`	number	是	无	调度任务 ID
`firstExecutionTime`	number	是	无	首次执行时间，Unix 秒级时间戳
`interval`	number	否	`3600`	执行间隔，单位秒

curl -X POST "http://127.0.0.1:43820/api/v1/cloud-mobile/schedule" \
  -H "Content-Type: application/json" \
  -d '{"scheduleId":1001,"firstExecutionTime":1760000000,"interval":3600}'

成功响应：

{
  "code": 0,
  "msg": "success",
  "data": {
    "scheduleId": 1001,
    "firstExecutionTime": 1760000000,
    "interval": 3600,
    "message": "Schedule created successfully"
  }
}

GET /api/v1/local-envs

查询本地云手机环境列表，支持 React Admin 风格 range、sort、filter 参数。

返回结果用于找到云手机设备。后续提交 RPA 时，设备 UUID 放在 envs 数组里。

curl "http://127.0.0.1:43820/api/v1/local-envs?range=[0,19]&sort=[%22id%22,%22ASC%22]&filter={}"

GET /api/v1/local-ips

查询本地云手机 IP 列表。

curl "http://127.0.0.1:43820/api/v1/local-ips"

GET /api/v1/task-polling/status

查询云手机 RPA 队列轮询状态。

这个接口主要用于排查 v2 队列任务。如果提交 v2 时 queued_count 为 0，这里可能没有活跃任务，这是正常情况。

curl "http://127.0.0.1:43820/api/v1/task-polling/status"

响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "activeTasks": 1,
    "tasks": {}
  }
}

GET /api/v1/schedule/status

查询云手机调度状态。

这个接口只反映云手机调度管理器状态，不表示 Platform RPA 计划任务状态。浏览器 RPA 的计划任务请使用 /api/v1/platform-rpa/schedules。

curl "http://127.0.0.1:43820/api/v1/schedule/status"

响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "activeSchedules": 1,
    "schedules": {}
  }
}

Platform RPA

Platform RPA 是当前浏览器 RPA 的推荐入口。它支持远程模板、本地脚本、运行方案、参数模板、计划任务和运行日志。

如果你要“让浏览器自动做一件事”，通常应该使用 Platform RPA，而不是直接调用浏览器 start 接口。浏览器 start 只负责打开窗口；Platform RPA 会负责选择脚本、准备参数、打开环境、连接 CDP、执行脚本和记录日志。

新接入推荐先跑通最小链路：

调用 /api/v1/platform-rpa/templates 找到模板。
调用 /api/v1/platform-rpa/templates/:templateId/meta 看模板需要哪些参数。
调用 /api/v1/platform-rpa/runs 创建运行。
用返回的 run_id 查询 /runs/:runId 和 /runs/:runId/events。

核心概念

概念	说明
远程模板	从 NestBrowser 服务端查询和缓存的 RPA 模板
本地脚本	本机导入或生成的 JS 脚本
运行	一次 RPA 执行任务，接口返回后异步执行
运行方案	可复用的运行配置快照
参数模板	可复用的变量集合
计划任务	基于运行方案和触发配置的定时执行

远程模板和本地脚本怎么选：

场景	推荐
使用官方或团队发布的脚本	远程模板，传 `script_source: "remote_template"` 和 `template_id`
自己开发或由 AI 生成脚本	本地脚本，传 `script_source: "local_script"` 和 `local_script_id`
不确定脚本需要哪些参数	先调用模板 meta 或本地脚本详情接口
想保存一套可复用配置	创建运行方案
想定时自动执行	创建 Platform RPA 计划任务

GET /api/v1/platform-rpa/templates

查询远程模板列表。

模板列表适合做“发现”和“搜索”。它不保证包含完整权限信息，也不保证参数信息完整。正式运行或收藏前，请再调用模板详情接口。

Query 参数：

参数	类型	默认值	说明
`limit`	number	`100`	返回数量，最大 200
`offset`	number	`0`	偏移量
`category`	string	无	分类
`search` / `q`	string	无	搜索关键字
`requires_midscene`	boolean	无	是否需要 Midscene

curl "http://127.0.0.1:43820/api/v1/platform-rpa/templates?category=Facebook&limit=20"

注意：模板列表只用于发现模板，不作为权限来源。运行、收藏前应读取模板详情。

如果模板运行或收藏失败，常见原因是当前 NestBrowser 登录账号没有购买该模板、模板已下架，或模板需要的功能权限没有开通。

GET /api/v1/platform-rpa/templates/:templateId/meta

查询模板详情并解析参数。

这个接口会返回模板原始信息和解析后的 params。params 是前端或三方系统生成表单时最重要的数据：它告诉你脚本需要哪些变量、类型是什么、是否必填、默认值是什么。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/templates/100/meta"

成功响应：

{
  "code": 0,
  "msg": "success",
  "data": {
    "template": {},
    "params": []
  }
}

GET /api/v1/platform-rpa/templates/:templateId/cache

查询远程模板在本机的脚本缓存状态。

远程模板运行前需要把脚本缓存到本机。常规运行时会自动刷新缺失缓存；如果你想提前排查脚本是否已下载，可以调用这个接口。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/templates/100/cache"

POST /api/v1/platform-rpa/templates/:templateId/cache/refresh

刷新模板脚本缓存。

当模板脚本更新、缓存损坏，或运行时提示脚本缓存不存在时，可以手动调用这个接口。刷新会访问远端模板脚本并写入本机用户数据目录。

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/templates/100/cache/refresh" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/v1/platform-rpa/template-favorites

查询本机收藏的模板。

收藏只是本机快捷入口，不是购买凭证。账号切换后，收藏记录还在，但运行前仍会按当前账号重新检查模板是否可用。

Query 参数：

参数	类型	默认值	说明
`limit`	number	`100`	返回数量，最大 200
`offset`	number	`0`	偏移量
`category`	string	无	分类
`status`	string	无	最近可运行状态

curl "http://127.0.0.1:43820/api/v1/platform-rpa/template-favorites"

POST /api/v1/platform-rpa/template-favorites/:templateId

收藏模板。只有当前账号可运行的模板才允许收藏。

如果返回购买或权限相关错误，说明模板本身存在，但当前账号暂时不能运行。先在 NestBrowser 客户端内确认登录状态和模板权益。

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/template-favorites/100" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/v1/platform-rpa/template-favorites/:templateId

取消收藏模板。

curl -X DELETE "http://127.0.0.1:43820/api/v1/platform-rpa/template-favorites/100"

GET /api/v1/platform-rpa/template-favorites/:templateId/status

按当前账号刷新并查询模板可运行状态。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/template-favorites/100/status"

GET /api/v1/platform-rpa/local-scripts

查询本机已导入或保存的脚本。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/local-scripts?category=Facebook"

POST /api/v1/platform-rpa/local-scripts/import

导入本地脚本。脚本应是构建后的 .js 或 .cjs 文件；如果不传 meta_path，服务端会尝试读取同名 .json。

本地脚本导入不是执行脚本，只是把脚本复制到 NestBrowser 的用户数据目录并记录元数据。导入成功后，再通过 /api/v1/platform-rpa/runs 执行。

元数据 JSON 用来描述脚本名称、分类、参数定义和默认值。如果缺少元数据，脚本可能可以保存，但三方系统很难知道应该让用户填写哪些参数。

Body 参数：

参数	类型	必填	说明
`script_path`	string	是	本机脚本路径
`meta_path`	string	否	本机元数据 JSON 路径
`category`	string	否	分类覆盖

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/local-scripts/import" \
  -H "Content-Type: application/json" \
  -d '{"script_path":"/path/to/script.js","meta_path":"/path/to/script.json","category":"Facebook"}'

POST /api/v1/platform-rpa/local-scripts/check

校验应用内 JS 和 JSON 草稿，不执行脚本。

这个接口适合在保存前做快速检查。它不会打开浏览器，也不会访问目标网站。

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/local-scripts/check" \
  -H "Content-Type: application/json" \
  -d '{"script":"await nAiStep(\"demo\", async () => {});","metadata":{"name":"Demo","category":"Facebook"}}'

POST /api/v1/platform-rpa/local-scripts/generate

根据自然语言生成脚本草稿。

生成接口依赖本机 AI/Midscene 配置。它只生成草稿，不代表脚本已经保存或执行成功。生成后建议先 check，再 save，最后 runs。

Body 参数：

参数	类型	必填	说明
`prompt`	string	是	生成需求
`category`	string	否	分类
`midscene_enabled`	boolean	否	是否启用 Midscene helper
`llm_doc`	string	否	额外工作文档
`current_script`	string	否	当前脚本，用于迭代
`current_metadata`	object	否	当前元数据

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/local-scripts/generate" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"打开 example.com 并截图","category":"Facebook"}'

POST /api/v1/platform-rpa/local-scripts/generate/stream

流式生成脚本草稿。响应为 SSE。

如果你的 HTTP 客户端不支持 SSE，可以使用非流式的 /generate。流式接口适合页面实时展示生成过程。

curl -N -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/local-scripts/generate/stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"prompt":"打开 example.com 并截图"}'

POST /api/v1/platform-rpa/local-scripts/save

保存应用内脚本草稿到本地脚本库。

保存成功后会生成或更新 local_script_id。后续运行本地脚本时，需要把这个 ID 传给 /api/v1/platform-rpa/runs。

Body 参数：

参数	类型	必填	说明
`script`	string	是	JS 脚本内容
`metadata`	object	否	脚本元数据
`category`	string	否	分类
`local_script_id`	string	否	更新已有脚本时传入
`backup`	boolean	否	是否备份旧版本

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/local-scripts/save" \
  -H "Content-Type: application/json" \
  -d '{"script":"await nAiScreenshotReport(\"page.png\");","metadata":{"name":"Demo","category":"Facebook"}}'

POST /api/v1/platform-rpa/local-scripts/run-from-prompt

按提示词生成本地脚本并立即创建运行任务。

这是一个快捷接口，适合探索性使用。正式生产链路更建议拆成 generate、check、save、runs 四步，这样更容易定位是生成问题、脚本问题，还是运行环境问题。

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/local-scripts/run-from-prompt" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"打开 example.com 并截图","env_ids":[123],"variables":{}}'

GET /api/v1/platform-rpa/local-scripts/:localScriptId

查询本地脚本详情。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/local-scripts/platform-rpa-smoke"

GET /api/v1/platform-rpa/local-scripts/:localScriptId/run-summaries

查询本地脚本最近运行摘要。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/local-scripts/platform-rpa-smoke/run-summaries?limit=10"

DELETE /api/v1/platform-rpa/local-scripts/:localScriptId

删除本地脚本记录和复制到用户数据目录的脚本文件。

curl -X DELETE "http://127.0.0.1:43820/api/v1/platform-rpa/local-scripts/platform-rpa-smoke"

Platform RPA 运行

POST /api/v1/platform-rpa/runs

创建一次 RPA 运行。接口返回后任务异步执行，调用方应继续查询运行详情和事件。

这是浏览器 RPA 最核心的提交接口。你可以把它理解为“创建一个执行单”。服务端收到请求后，会按环境打开浏览器、连接 CDP、注入参数、执行脚本、写入日志和报告。

这个接口不会等脚本全部执行完再返回。返回成功只代表运行任务已创建。要知道最终成功还是失败，必须继续查询 run 详情和 events。

Body 参数：

参数	类型	必填	说明
`category`	string	是	脚本分类
`script_source`	string	否	`remote_template` 或 `local_script`，默认 `remote_template`
`template_id`	number	远程模板必填	远程模板 ID
`local_script_id`	string	本地脚本必填	本地脚本 ID
`variables`	object	否	通用参数
`env_variables`	object	否	按环境覆盖的参数，key 为环境 ID 或 UUID
`env_ids`	number[]	二选一	环境 ID 列表
`group_id`	number	二选一	分组 ID
`local_chrome`	object	否	本地 Chrome 运行选项
`options`	object	否	并发、缓存、关闭浏览器等选项

关键字段怎么理解：

字段	通俗解释
`script_source`	选择脚本来源。不传时默认远程模板
`template_id`	远程模板 ID，用官方/团队模板时传这个
`local_script_id`	本地脚本 ID，用自己导入或 AI 生成脚本时传这个
`variables`	所有环境共用的参数
`env_variables`	某个环境单独覆盖的参数；适合每个账号填不同内容
`env_ids`	明确指定哪些浏览器环境执行
`group_id`	不想逐个传环境时，可以按分组批量执行

远程模板运行示例：

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/runs" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "Facebook",
    "script_source": "remote_template",
    "template_id": 100,
    "env_ids": [123],
    "variables": {},
    "options": {
      "concurrency": 5,
      "auto_refresh_cache": true
    }
  }'

本地脚本运行示例：

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/runs" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "Facebook",
    "script_source": "local_script",
    "local_script_id": "platform-rpa-smoke",
    "env_ids": [123],
    "variables": {
      "url": "https://example.com"
    }
  }'

options 支持：

参数	类型	默认值	说明
`concurrency`	number	`5`	并发执行环境数
`source`	string	`manual`	`manual` 或 `schedule`
`schedule_id`	number	无	计划任务触发时携带
`auto_refresh_cache`	boolean	`true`	缓存缺失时自动刷新远程模板脚本
`close_browser_after_run`	boolean	取决于页面配置	运行后是否关闭浏览器

如果你不知道怎么填，最小请求只需要：category、template_id 或 local_script_id、env_ids。参数可以先传 {}，等模板 meta 告诉你需要哪些参数后再补。

常见失败原因：

现象	常见原因
提示模板不可运行	当前账号没有模板权限、模板收费未购买，或模板不存在
提示脚本缓存不存在	远程模板脚本未下载，保持 `auto_refresh_cache: true` 或手动刷新缓存
没有环境可运行	`env_ids` 不存在，或 `group_id` 下没有账号环境
run 创建成功但后续失败	浏览器打开失败、页面加载失败、脚本逻辑失败；查 events

GET /api/v1/platform-rpa/runs

查询运行列表。

列表适合做历史记录、分页展示和按状态筛选。它不是实时日志接口；查看单次运行过程请用 run 详情和 events。

Query 参数：

参数	类型	默认值	说明
`limit`	number	`50`	返回数量，最大 200
`offset`	number	`0`	偏移量
`status`	string	无	运行状态
`category`	string	无	分类
`template_id`	number	无	远程模板 ID
`template_uuid`	string	无	模板 UUID 或本地脚本 ID
`local_script_id`	string	无	本地脚本 ID

curl "http://127.0.0.1:43820/api/v1/platform-rpa/runs?limit=20&offset=0"

GET /api/v1/platform-rpa/runs/:runId

查询运行详情和环境级运行状态。

一个 run 可能包含多个环境。详情里通常能看到主任务状态，以及每个环境的执行状态。批量运行时，不要只看主状态，也要看环境级状态。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/runs/run_001"

GET /api/v1/platform-rpa/runs/:runId/events

查询运行事件。

这是排查 RPA 问题最重要的接口。脚本步骤、错误消息、截图/报告路径等通常会写在事件里。建议运行中每 1-2 秒轮询一次，结束后停止轮询。

Query 参数：

参数	类型	默认值	说明
`env_run_id`	number	无	按环境运行记录过滤
`env_id`	number	无	按环境 ID 过滤
`after_id`	number	`0`	只返回指定 ID 之后的事件
`limit`	number	`200`	返回数量上限

curl "http://127.0.0.1:43820/api/v1/platform-rpa/runs/run_001/events?after_id=0&limit=100"

GET /api/v1/platform-rpa/runs/:runId/artifacts/open

读取运行产物文件。path 必须指向该运行报告目录内的文件。

产物通常来自脚本主动写入的报告文件、截图、日志或 JSON 结果。这个接口只允许读取当前 run 报告目录内的文件，避免任意读取本机文件。

Query 参数：

参数	类型	必填	说明
`path`	string	是	产物相对路径或受限绝对路径

curl "http://127.0.0.1:43820/api/v1/platform-rpa/runs/run_001/artifacts/open?path=env_123/report.json"

文本类产物会以内联方式返回。

DELETE /api/v1/platform-rpa/runs/:runId

删除运行记录、环境记录和事件日志。

删除后历史日志不可恢复。建议只在确认不再需要审计或排查时调用。

curl -X DELETE "http://127.0.0.1:43820/api/v1/platform-rpa/runs/run_001"

Platform RPA 运行方案

GET /api/v1/platform-rpa/run-profiles

查询运行方案列表。

运行方案是“保存好的一套运行配置”。如果用户经常用同一个模板、同一批环境、同一组参数运行，可以先保存成方案，再从方案创建计划任务或手动复用。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/run-profiles?limit=20&offset=0"

POST /api/v1/platform-rpa/run-profiles

创建运行方案。

run_request_snapshot 本质上就是一次 /api/v1/platform-rpa/runs 请求的快照。保存方案不会执行 RPA，只是把配置存起来。

Body 参数：

参数	类型	必填	说明
`name`	string	是	方案名称
`remark`	string	否	备注
`run_request_snapshot`	object	是	`/runs` 请求快照
`form_snapshot`	object	否	页面表单快照
`ai_materials_snapshot`	object	否	AI 素材快照

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/run-profiles" \
  -H "Content-Type: application/json" \
  -d '{"name":"Daily Run","run_request_snapshot":{"category":"Facebook","template_id":100,"env_ids":[123]}}'

GET /api/v1/platform-rpa/run-profiles/:id

查询运行方案详情。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/run-profiles/1"

PUT /api/v1/platform-rpa/run-profiles/:id

更新运行方案。

更新方案只影响以后使用该方案的运行或计划任务，不会修改已经创建的历史 run。

curl -X PUT "http://127.0.0.1:43820/api/v1/platform-rpa/run-profiles/1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Daily Run"}'

POST /api/v1/platform-rpa/run-profiles/:id/touch

更新运行方案最近使用状态。

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/run-profiles/1/touch" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/v1/platform-rpa/run-profiles/:id

删除运行方案。

curl -X DELETE "http://127.0.0.1:43820/api/v1/platform-rpa/run-profiles/1"

Platform RPA 参数模板

GET /api/v1/platform-rpa/param-templates

查询参数模板列表。

参数模板是“保存好的一组变量值”。它通常和计划任务一起使用，例如同一个脚本要对不同账号轮换不同关键词、链接、文案或文件。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/param-templates?category=Facebook"

POST /api/v1/platform-rpa/param-templates

创建参数模板。

values 里放脚本真正需要的参数。参数名应和模板 meta 或本地脚本详情里的参数名一致。

Body 参数：

参数	类型	必填	说明
`name`	string	是	模板名称
`remark`	string	否	备注
`category`	string	是	分类
`script_source`	string	是	`remote_template` 或 `local_script`
`template_id`	number	否	远程模板 ID
`local_script_id`	string	否	本地脚本 ID
`values`	object	是	参数值
`tags`	string[]	否	标签

如果参数模板用于某个远程模板，建议传 template_id。如果用于本地脚本，建议传 local_script_id。这样后续筛选和计划任务选择会更准确。

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/param-templates" \
  -H "Content-Type: application/json" \
  -d '{"name":"Default Params","category":"Facebook","script_source":"remote_template","template_id":100,"values":{"url":"https://example.com"}}'

GET /api/v1/platform-rpa/param-templates/:id

查询参数模板详情。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/param-templates/1"

PUT /api/v1/platform-rpa/param-templates/:id

更新参数模板。

curl -X PUT "http://127.0.0.1:43820/api/v1/platform-rpa/param-templates/1" \
  -H "Content-Type: application/json" \
  -d '{"values":{"url":"https://example.org"}}'

DELETE /api/v1/platform-rpa/param-templates/:id

删除参数模板。

curl -X DELETE "http://127.0.0.1:43820/api/v1/platform-rpa/param-templates/1"

Platform RPA 计划任务

Platform RPA 计划任务不独立执行脚本，而是保存运行配置快照，到点后复用 /api/v1/platform-rpa/runs。

计划任务适合“以后自动运行”或“按周期运行”。它不是立即执行接口；创建成功后，调度器会根据触发配置在合适的时间创建 run。

如果你只是想现在跑一次，请直接调用 /api/v1/platform-rpa/runs。如果你想马上验证某个计划任务，可以创建后调用 /api/v1/platform-rpa/schedules/:id/run-now。

GET /api/v1/platform-rpa/schedules

查询计划任务列表。

列表用于后台管理所有计划任务。当前任务是否真的跑过，要看 last_run_at、last_run_id 和 fires 记录。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/schedules?limit=20&offset=0"

GET /api/v1/platform-rpa/schedules/stats

查询计划任务统计。

统计适合页面仪表盘展示，例如启用数量、停用数量、最近执行情况等。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/schedules/stats"

POST /api/v1/platform-rpa/schedules

创建计划任务。

创建计划任务最容易填错的是 run_profile_snapshot 和 trigger_config：

run_profile_snapshot.run_request_snapshot 要能构造成一次有效的 /runs 请求。
trigger_config 的格式取决于 trigger_type。
如果使用参数轮换或消耗，param_template_ids 要传可用的参数模板 ID。

Body 参数：

参数	类型	必填	说明
`name`	string	是	任务名称
`remark`	string	否	备注
`status`	string	否	`enabled` 或 `disabled`
`trigger_type`	string	是	`once`、`interval`、`daily`、`weekly`、`cron`
`trigger_config`	object	是	触发配置
`run_profile_snapshot`	object	是	运行方案快照，需包含 `run_request_snapshot`
`param_mode`	string	否	`fixed`、`rotate`、`consume`
`param_template_ids`	number[]	否	参数模板 ID 列表

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/schedules" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly RPA",
    "status": "enabled",
    "trigger_type": "interval",
    "trigger_config": { "minutes": 60 },
    "run_profile_snapshot": {
      "run_request_snapshot": {
        "category": "Facebook",
        "template_id": 100,
        "env_ids": [123]
      }
    },
    "param_mode": "fixed"
  }'

触发配置：

`trigger_type`	`trigger_config`	说明
`once`	`{ "run_at": "2026-06-16T09:00:00.000Z" }`	单次运行
`interval`	`{ "minutes": 60 }`	每 N 分钟运行
`daily`	`{ "time": "09:00" }`	每天固定时间
`weekly`	`{ "time": "09:00", "weekdays": [1,3,5] }`	指定星期运行
`cron`	`{ "expression": "0 9 * * *" }`	Cron 表达式

时间字段建议使用 ISO 字符串或前端页面生成的配置。跨时区部署时，请先用测试任务确认触发时间符合预期。

GET /api/v1/platform-rpa/schedules/:id

查询计划任务详情。

详情比列表更适合排查问题，因为它包含触发配置、运行快照、上次运行结果和下次运行时间等信息。

curl "http://127.0.0.1:43820/api/v1/platform-rpa/schedules/1"

PUT /api/v1/platform-rpa/schedules/:id

更新计划任务。更新后服务会刷新对应调度 job。

如果你修改了触发时间、状态或运行快照，更新后下一次触发会使用新配置。已经创建的历史 run 不会被修改。

curl -X PUT "http://127.0.0.1:43820/api/v1/platform-rpa/schedules/1" \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

POST /api/v1/platform-rpa/schedules/:id/toggle

启用或停用计划任务。

停用后不会继续自动触发，但历史记录仍保留。再次启用后，服务会重新计算后续触发。

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/schedules/1/toggle" \
  -H "Content-Type: application/json" \
  -d '{"status":"enabled"}'

POST /api/v1/platform-rpa/schedules/:id/run-now

立即运行计划任务。服务会构造 /runs 请求并写入触发记录。

run-now 常用于测试计划任务配置。它会复用计划任务里保存的运行快照和参数策略，因此比手动重新组装 /runs 请求更接近真实定时触发。

curl -X POST "http://127.0.0.1:43820/api/v1/platform-rpa/schedules/1/run-now" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/v1/platform-rpa/schedules/:id/fires

查询计划任务触发记录。

fires 记录包含 started、skipped、failed 等结果。计划任务没产生 run 时，也可能有 skipped 记录，例如同一个 schedule 已有运行还没结束，或消耗模式参数已经用完。

Query 参数：

参数	类型	默认值	说明
`limit`	number	`50`	返回数量，最大 200
`offset`	number	`0`	偏移量

curl "http://127.0.0.1:43820/api/v1/platform-rpa/schedules/1/fires?limit=20"

DELETE /api/v1/platform-rpa/schedules/:id

删除计划任务，并移除对应调度 job。

删除后不会再自动触发。已经创建的 run 记录不一定会被删除，仍可在运行列表里查看。

curl -X DELETE "http://127.0.0.1:43820/api/v1/platform-rpa/schedules/1"

状态枚举

Platform RPA 运行状态

状态	说明
`opening`	正在打开环境
`running`	正在执行
`success`	执行成功
`failed`	执行失败
`cancelled`	已取消

Platform RPA 计划任务状态

状态	说明
`enabled`	启用
`disabled`	停用

参数策略

策略	说明
`fixed`	每次使用创建任务时保存的参数快照
`rotate`	按环境数量从参数模板列表循环取值
`consume`	消耗参数模板，全部耗尽后停用任务

错误处理建议

场景	建议
`code` 为 `-1`	读取 `msg`，检查参数和本地应用日志
HTTP 404	确认端口、路径和方法
浏览器打开失败	查询账号是否存在、环境是否已被锁定、本机资源是否足够
Platform RPA 运行失败	查询 `/runs/:runId` 和 `/runs/:runId/events`
云手机任务未继续执行	查询 `/api/v1/task-polling/status`
计划任务未触发	查询计划任务详情、统计和 fires 记录

常见问题

为什么我传了 Authorization 还是失败？

当前本地 HTTP API 没有统一校验 Authorization。如果你看到权限相关失败，通常是业务权限失败，例如模板未购买、当前客户端未登录、账号没有相关功能权限，而不是 Header 格式不对。

`id`、`uuid`、`user_id`、`serial_number` 到底用哪个？

账号数字 ID 通常叫 id 或 serial_number；账号字符串 UUID 通常叫 uuid 或 user_id。浏览器打开接口两种都支持。新接入建议优先用数字 ID，因为账号列表和创建接口都会返回 serial_number。

`/runs` 返回 success，为什么脚本还没跑完？

Platform RPA 是异步任务。/runs 返回 success 表示任务已创建，不表示脚本最终成功。后续要查 /runs/:runId 和 /runs/:runId/events。

为什么模板列表里看到了模板，但运行失败？

模板列表只用于发现，不作为权限来源。运行前服务会读取模板详情并检查当前账号是否可运行。收费模板未购买、账号未登录、模板下架都可能导致运行失败。

云手机接口和浏览器 RPA 接口能混用吗？

不能混用。云手机的 envs 是云手机设备 UUID；Platform RPA 的 env_ids 是浏览器账号环境 ID。两套资源和执行器不同。

计划任务到了时间没执行，先看哪里？

先查计划任务详情，确认 status、next_run_at、触发配置和运行快照。再查 /schedules/:id/fires，看是否被 skipped。最后根据 last_run_id 查 run 详情和 events。

版本兼容说明

本文只覆盖推荐的公开本地 API。应用内部仍可能存在用于旧页面、调试、缓存管理或私有 Socket.IO 通信的路由，这些不作为三方集成契约。

浏览器 RPA、浏览器计划任务、浏览器参数和运行方案以 Platform RPA 接口为准。云手机 API 独立保留。

NestBrowser API 参考

NestBrowser 本地三方 API 文档

快速开始

Base URL

健康检查

安全边界

响应格式

分页参数

异步任务约定

关键名词

接口总览

系统状态

GET /status

账号与分组

POST /api/v1/user/create

POST /api/v1/user/update

GET /api/v1/user/list

POST /api/v1/user/delete

POST /api/v1/user/regroup

POST /api/v1/group/create

POST /api/v1/group/update

GET /api/v1/group/list

浏览器环境

GET /api/v1/browser/start

POST /api/v1/browser/start

GET /api/v1/browser/stop

GET /api/v1/browser/active

云手机

POST /api/v1/cloud-mobile/rpa

POST /api/v2/cloud-mobile/rpa

POST /api/v1/cloud-mobile/schedule

GET /api/v1/local-envs

GET /api/v1/local-ips

GET /api/v1/task-polling/status

GET /api/v1/schedule/status

Platform RPA

核心概念

GET /api/v1/platform-rpa/templates

GET /api/v1/platform-rpa/templates/:templateId/meta

GET /api/v1/platform-rpa/templates/:templateId/cache

POST /api/v1/platform-rpa/templates/:templateId/cache/refresh

GET /api/v1/platform-rpa/template-favorites

POST /api/v1/platform-rpa/template-favorites/:templateId

DELETE /api/v1/platform-rpa/template-favorites/:templateId

GET /api/v1/platform-rpa/template-favorites/:templateId/status

GET /api/v1/platform-rpa/local-scripts

POST /api/v1/platform-rpa/local-scripts/import

POST /api/v1/platform-rpa/local-scripts/check

POST /api/v1/platform-rpa/local-scripts/generate

POST /api/v1/platform-rpa/local-scripts/generate/stream

POST /api/v1/platform-rpa/local-scripts/save

POST /api/v1/platform-rpa/local-scripts/run-from-prompt

GET /api/v1/platform-rpa/local-scripts/:localScriptId

GET /api/v1/platform-rpa/local-scripts/:localScriptId/run-summaries

DELETE /api/v1/platform-rpa/local-scripts/:localScriptId

Platform RPA 运行

POST /api/v1/platform-rpa/runs

GET /api/v1/platform-rpa/runs

GET /api/v1/platform-rpa/runs/:runId

GET /api/v1/platform-rpa/runs/:runId/events

GET /api/v1/platform-rpa/runs/:runId/artifacts/open

DELETE /api/v1/platform-rpa/runs/:runId

Platform RPA 运行方案

GET /api/v1/platform-rpa/run-profiles

POST /api/v1/platform-rpa/run-profiles

GET /api/v1/platform-rpa/run-profiles/:id

PUT /api/v1/platform-rpa/run-profiles/:id

POST /api/v1/platform-rpa/run-profiles/:id/touch

DELETE /api/v1/platform-rpa/run-profiles/:id

Platform RPA 参数模板

GET /api/v1/platform-rpa/param-templates

POST /api/v1/platform-rpa/param-templates

GET /api/v1/platform-rpa/param-templates/:id

PUT /api/v1/platform-rpa/param-templates/:id

DELETE /api/v1/platform-rpa/param-templates/:id

Platform RPA 计划任务

GET /api/v1/platform-rpa/schedules

GET /api/v1/platform-rpa/schedules/stats

POST /api/v1/platform-rpa/schedules

GET /api/v1/platform-rpa/schedules/:id

`id`、`uuid`、`user_id`、`serial_number` 到底用哪个？

`/runs` 返回 success，为什么脚本还没跑完？