浏览器窗口

浏览器窗口的分页查询、创建、代理绑定与解绑、平台账号绑定与解绑、移动到窗口分组、读取已打开窗口保险库、打开与关闭，以及读取本机 CDP 连接信息。窗口标识统一使用 windowId，取自 /browser/list 的 data.data[].id。

分组本身的增删改查见 窗口分组。

在本页搜索

显示 9 / 9 个接口

GET/browser/list

窗口列表

按当前登录团队分页查询窗口，并附带窗口绑定的代理、平台账号与插件。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
teamId	string | number	可选	团队 ID；缺省使用当前登录团队
page	number	可选	页码，默认 1
size	number	可选	每页数量，默认 20，服务端上限 1000
keyword	string	可选	关键词，模糊匹配窗口名称
groupId	number	可选	不传查询全部；0 查询未分组；正数查询指定分组；负数返回参数错误

响应字段

字段	类型	说明
data.count	number	匹配到的总条数
data.size	number	每页数量，回显请求值
data.page	number	当前页码，回显请求值
data.total	number	总页数
data.data	object[]	当前页记录
data.data[].id	number	窗口主键 ID，各窗口接口的 windowId 取该值
data.data[].name	string	窗口名称
data.data[].userId	number	归属用户 ID
data.data[].teamId	number	归属团队 ID
data.data[].groupId	number	窗口分组 ID，0 表示未分组
data.data[].seq	number	排序值
data.data[].platformId	string	绑定平台账号 ID 数组的 JSON 文本
data.data[].pluginId	string	安装插件 ID 数组的 JSON 文本
data.data[].proxyId	number	绑定代理 ID，0 表示未绑定
data.data[].remark	string	窗口描述
data.data[].uuid	string	窗口目录唯一标识
data.data[].languageFrame	string	界面语言，"0" 表示跟随 IP
data.data[].languageView	string	网页语言，auto/"0" 表示跟随 IP
data.data[].timezone	string	时区，auto/"0" 表示跟随 IP
data.data[].location	string	经纬度，逗号分隔，"0,0" 表示跟随 IP
data.data[].locationAssable	number	定位权限：0 禁止、1 询问、2 允许
data.data[].audioSwitch	string	音频开关：ON、OFF
data.data[].pictureSwitch	string	图片开关：ON、OFF
data.data[].videoSwitch	string	视频开关：ON、OFF
data.data[].screenPixel	string	分辨率 "宽,高"，"0,0" 表示全屏
data.data[].screenLocation	string	窗口打开位置
data.data[].opened	string	是否已打开：ON、OFF
data.data[].openedUserId	number	当前持有打开状态的用户 ID
data.data[].activeAt	string	最后活跃时间，未打开过为 null
data.data[].createdAt	string	创建时间 yyyy-MM-dd HH:mm:ss
data.data[].updatedAt	string	更新时间 yyyy-MM-dd HH:mm:ss
data.data[].userEmail	string	归属用户邮箱
data.data[].proxy	object	绑定的代理详情，未绑定为 null；字段同 /proxy/list 条目
data.data[].platforms	object[]	绑定的平台账号，字段同 /account/list 条目（含明文密码与 2FA 密钥）
data.data[].plugins	object[]	已安装插件

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 1,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 8001,
        "name": "示例环境-01",
        "userId": 1001,
        "teamId": 2001,
        "groupId": 0,
        "seq": 1,
        "platformId": "[5001,5002]",
        "pluginId": "[]",
        "proxyId": 0,
        "remark": "",
        "uuid": "7c2b5e9a41d84f10b6c3e0a95d824fb7",
        "languageFrame": "0",
        "languageView": "auto",
        "timezone": "auto",
        "location": "0,0",
        "locationAssable": 1,
        "audioSwitch": "ON",
        "pictureSwitch": "ON",
        "videoSwitch": "ON",
        "screenPixel": "1920,1080",
        "screenLocation": "LEFT",
        "opened": "OFF",
        "openedUserId": 1001,
        "activeAt": null,
        "createdAt": "2026-06-01 12:30:00",
        "updatedAt": "2026-06-01 12:30:00",
        "userEmail": "[email protected]",
        "proxy": null,
        "platforms": [
          {
            "id": 5001,
            "userId": 1001,
            "teamId": 2001,
            "platformUrl": "https://x.com/",
            "username": "demo_account",
            "password": "demo-password",
            "key2fa": "JBSWY3DPEHPK3PXP",
            "remark": "",
            "state": 0,
            "createdAt": "2026-01-15 10:00:00",
            "updatedAt": "2026-06-01 12:30:00",
            "userEmail": "[email protected]",
            "icon": "https://oss.nexbrowser.net/images/platform_icon/twitter.png",
            "bindScreen": [
              {
                "id": 8001,
                "uuid": "7c2b5e9a41d84f10b6c3e0a95d824fb7",
                "name": "示例环境-01"
              }
            ]
          }
        ],
        "plugins": []
      }
    ]
  }
}

POST/browser/create

创建浏览器窗口

按客户端「创建窗口」弹窗的默认值批量建窗，每个窗口单独申请一份独立指纹。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
count	number	可选	创建数量，默认 1，单次上限 50，超限直接返回业务失败
name	string	可选	窗口名；count>1 时自动追加 -01、-02 序号后缀
groupId	number	可选	窗口分组 ID，0 表示未分组
remark	string	可选	窗口描述
proxyId	number	可选	绑定的代理 ID，0 表示不绑定
accountIds	number[] | string	可选	绑定的平台账号 ID，数组或逗号分隔文本
pluginIds	string[] | string	可选	安装的插件 ID，数组或逗号分隔文本
startupUrl	string	可选	窗口启动页
screen	object	可选	窗口字段覆盖项，键同 /browser/list 条目
preference	object	可选	偏好设置覆盖项
fingerprint	object	可选	指纹覆盖项，可指定 osType、osVersion、coreVersion 等

注意事项

• 未传的字段一律沿用客户端默认值；全部窗口都失败时接口返回业务失败并汇总错误信息。

响应字段

字段	类型	说明
data.rows	object[]	逐个窗口的创建结果
data.rows[].seq	number	本次批量中的序号，从 1 开始
data.rows[].name	string	实际使用的窗口名
data.rows[].success	boolean	该窗口是否创建成功
data.rows[].id	string	窗口 ID，成功时返回
data.rows[].uuid	string	窗口目录唯一标识，成功时返回
data.rows[].error	string	失败原因，成功时缺省
data.success	number	成功行数
data.failed	number	失败行数
data.total	number	总行数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "rows": [
      {
        "seq": 1,
        "name": "自动化环境-01",
        "success": true,
        "id": "8002",
        "uuid": "9f1c7f6f0b1c42f6a0c9d3b2e5a7c418"
      },
      {
        "seq": 2,
        "name": "自动化环境-02",
        "success": true,
        "id": "8003",
        "uuid": "b3d5a1c8e47f4a02b6d9c0f8a2e14d73"
      }
    ],
    "success": 2,
    "failed": 0,
    "total": 2
  }
}

POST/browser/proxy

绑定或解绑窗口代理

为一个或多个已关闭的窗口绑定代理；proxyId 传 0 表示解绑。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowIds	string[]	必填	一个或多个窗口 ID
proxyId	string | number	必填	代理 ID；传 0 移除绑定。缺省返回参数错误

注意事项

• 窗口处于打开状态时该行会失败；全部失败时接口返回业务失败并汇总错误信息。
• 兼容旧调用：windowIds 也可写成 windowId，单值或数组同样接受。

响应字段

字段	类型	说明
data.rows	object[]	逐个窗口的绑定结果
data.rows[].windowId	string	窗口 ID
data.rows[].proxyId	string | number	本次写入的代理 ID
data.rows[].success	boolean	该窗口是否绑定成功
data.rows[].error	string	失败原因，成功时缺省
data.success	number	成功行数
data.failed	number	失败行数
data.total	number	总行数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "rows": [
      {
        "windowId": "8001",
        "proxyId": 6001,
        "success": true
      }
    ],
    "success": 1,
    "failed": 0,
    "total": 1
  }
}

POST/browser/account

绑定或解绑窗口平台账号

给已关闭的窗口选择平台账号。`accountIds` 传入要绑定的账号 ID 列表；传入 `[]` 表示不选择账号。本次写入会整组替换原绑定。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowIds	string[]	必填	一个或多个窗口 ID；也可以用 windowId 传单个 ID 或 ID 数组
accountIds	number[]	必填	平台账号 ID 列表。传入一个或多个账号 ID 表示绑定；传入 [] 表示不选择账号。缺省返回参数错误

注意事项

• 实际写入窗口的 platformId 是 JSON 数组文本：绑定为 accountIds 的 JSON 文本，不选择账号为 "[]"。
• 窗口正在运行或写入失败时返回业务失败；成功时 data 为 null。

响应字段

字段	类型	说明
data	null	无返回数据，成功以 code=0 表示

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": null
}

POST/browser/group

移动窗口到分组

把一个或多个窗口移动到指定窗口分组；groupId 传 0 表示移出分组。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowIds	string[]	必填	一个或多个窗口 ID；也可以用 windowId 传单个 ID 或 ID 数组
groupId	string | number	必填	目标分组 ID；传 0 移出分组。缺省返回参数错误

注意事项

• 分组只是窗口元数据，窗口处于打开状态时同样可以移动，无需先关闭。
• 全部失败时接口返回业务失败并汇总错误信息。

响应字段

字段	类型	说明
data.rows	object[]	逐个窗口的移动结果
data.rows[].windowId	string	窗口 ID
data.rows[].groupId	number	本次写入的分组 ID
data.rows[].success	boolean	该窗口是否移动成功
data.rows[].error	string	失败原因，成功时缺省
data.success	number	成功行数
data.failed	number	失败行数
data.total	number	总行数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "rows": [
      {
        "windowId": "8001",
        "groupId": 5002,
        "success": true
      }
    ],
    "success": 1,
    "failed": 0,
    "total": 1
  }
}

GET/browser/accounts

查询窗口可填充账号

读取已打开窗口里可以自动填登录的账号，包括已绑定的平台账号，以及用户自己保存的密码。用户名已脱敏，密码和 2FA 密钥不会出现在响应里。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowId	string | string[]	必填	窗口数字 ID，支持单值、逗号分隔文本或重复传参；不接受窗口 uuid

注意事项

• 本接口只读，不负责给窗口选账号。选择或取消平台账号请用 POST /browser/account：传入 accountIds 绑定，传入 [] 表示不选择账号。
• 密码与 2FA 密钥只在 /automation/sessions/:sessionId/account_fill 的填表路径内使用，不经本接口外发。
• 账号条目还有一个恒为空串的 platformId 字段，请用 platformUrl 或 platformName 识别平台。

响应字段

字段	类型	说明
data	object[]	逐个窗口的查询结果
data[].windowId	string	窗口 ID
data[].windowName	string	窗口名称，成功时返回
data[].success	boolean	该窗口是否查询成功
data[].error	string	失败原因，成功时缺省
data[].accounts	object[]	绑定的平台账号（脱敏视图）
data[].accounts[].accountId	string	平台账号 ID
data[].accounts[].platformName	string	平台名，按 platformUrl 主机名推导
data[].accounts[].platformUrl	string	平台站点链接
data[].accounts[].username	string	脱敏后的登录名
data[].accounts[].remark	string	备注
data[].accounts[].hasPassword	boolean	是否存有密码
data[].accounts[].has2fa	boolean	2FA 密钥是否可用于生成验证码

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "windowId": "8001",
      "windowName": "示例环境-01",
      "success": true,
      "accounts": [
        {
          "accountId": "5001",
          "platformName": "x.com",
          "platformUrl": "https://x.com/",
          "username": "de**********nt",
          "remark": "",
          "hasPassword": true,
          "has2fa": true
        }
      ]
    }
  ]
}

POST/browser/open

打开浏览器窗口

按窗口 ID 启动一个或多个浏览器环境，并尽力补充 CDP 连接端点。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
teamId	string	必填	当前团队 ID；缺省返回业务失败
ids	string[]	必填	窗口 ID 数组

注意事项

• 传入单个窗口时 data 为该窗口对象；传入多个窗口时 data 为 rows 批量结构。
• 窗口已启动但 CDP 端点解析失败时不回滚窗口，改为在该行补 cdpError 字段。
• 兼容旧调用：ids 也可写成 windowId 或 id，单值或数组同样接受。

响应字段

字段	类型	说明
data.ok	boolean	内核启动结果
data.id	string	窗口 ID
data.windowId	string	窗口 ID，与 data.id 取值相同
data.key	string	本机运行实例标识
data.profileDir	string	窗口 profile 目录
data.running	boolean	窗口是否处于运行中
data.success	boolean	本行是否成功
data.alreadyRunning	boolean	调用前窗口是否已在运行
data.ws	string	CDP WebSocket 地址
data.cdpEndpoint	string	CDP WebSocket 地址，与 data.ws 取值相同
data.http	string	CDP HTTP 地址
data.cdpHttpEndpoint	string	CDP HTTP 地址，与 data.http 取值相同
data.cdpPort	number	CDP 端口
data.devToolsActivePortPath	string	DevToolsActivePort 文件路径
data.cdpError	string	CDP 端点解析失败时的原因
data.rows	object[]	传入多个窗口时的逐行结果，字段同上
data.success	number	成功行数
data.failed	number	失败行数
data.total	number	总行数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "ok": true,
    "id": "8001",
    "windowId": "8001",
    "key": "8001",
    "profileDir": "C:\\Users\\demo\\AppData\\Roaming\\NexBrowser\\profiles\\8001",
    "running": true,
    "success": true,
    "alreadyRunning": false,
    "ws": "ws://127.0.0.1:9222/devtools/browser/6f1c-42f6-a0c9",
    "http": "http://127.0.0.1:9222",
    "cdpEndpoint": "ws://127.0.0.1:9222/devtools/browser/6f1c-42f6-a0c9",
    "cdpHttpEndpoint": "http://127.0.0.1:9222",
    "cdpPort": 9222,
    "devToolsActivePortPath": "C:\\Users\\demo\\AppData\\Roaming\\NexBrowser\\profiles\\8001\\DevToolsActivePort"
  }
}

GET/browser/connection_info

浏览器连接信息

读取运行中浏览器的 CDP 连接信息；不传窗口时返回全部已打开窗口。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
windowId	string | string[]	可选	窗口 ID，支持单值、逗号分隔文本或重复传参；不传返回全部运行中的窗口

注意事项

• 只返回运行中的窗口，未运行的窗口会被过滤掉；没有窗口运行时 data 为空数组。

响应字段

字段	类型	说明
data	object[]	运行中的窗口连接信息
data[].id	string	窗口 ID
data[].windowId	string	窗口 ID，与 data[].id 取值相同
data[].key	string	本机运行实例标识
data[].profileDir	string	窗口 profile 目录
data[].running	boolean	固定为 true
data[].success	boolean	固定为 true
data[].ws	string	CDP WebSocket 地址
data[].cdpEndpoint	string	CDP WebSocket 地址，与 data[].ws 取值相同
data[].http	string	CDP HTTP 地址
data[].cdpHttpEndpoint	string	CDP HTTP 地址，与 data[].http 取值相同
data[].cdpPort	number	CDP 端口
data[].devToolsActivePortPath	string	DevToolsActivePort 文件路径

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": [
    {
      "id": "8001",
      "windowId": "8001",
      "key": "8001",
      "profileDir": "C:\\Users\\demo\\AppData\\Roaming\\NexBrowser\\profiles\\8001",
      "running": true,
      "success": true,
      "ws": "ws://127.0.0.1:9222/devtools/browser/6f1c-42f6-a0c9",
      "http": "http://127.0.0.1:9222",
      "cdpEndpoint": "ws://127.0.0.1:9222/devtools/browser/6f1c-42f6-a0c9",
      "cdpHttpEndpoint": "http://127.0.0.1:9222",
      "cdpPort": 9222,
      "devToolsActivePortPath": "C:\\Users\\demo\\AppData\\Roaming\\NexBrowser\\profiles\\8001\\DevToolsActivePort"
    }
  ]
}

POST/browser/close

关闭浏览器窗口

关闭一个或多个运行中的浏览器窗口，并返回批量结果。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
ids	string[]	必填	一个或多个窗口 ID；缺省返回业务失败
teamId	string	可选	可选团队 ID，用于释放服务端的窗口打开状态

注意事项

• 窗口本就未运行时该行返回 success=false 且 error 为 "Browser is not running: <id>"。
• 兼容旧调用：ids 也可写成 windowId 或 id，单值或数组同样接受。

响应字段

字段	类型	说明
data.rows	object[]	逐个窗口的关闭结果
data.rows[].id	string	窗口 ID
data.rows[].key	string	本机运行实例标识
data.rows[].success	boolean	该窗口是否关闭成功
data.rows[].error	string	失败原因，成功时缺省
data.success	number	成功行数
data.failed	number	失败行数
data.total	number	总行数

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "rows": [
      {
        "id": "8001",
        "key": "8001",
        "success": true
      }
    ],
    "success": 1,
    "failed": 0,
    "total": 1
  }
}