Browser Windows

Page through browser windows, create and rename them, bind or unbind proxies and platform accounts, move them into window groups, read the vault of an open window, open and close windows, and read local CDP connection info. Windows are always identified by windowId, taken from data.data[].id of /browser/list.

To create, rename, or delete the groups themselves, see Window Groups.

Search this page

Showing 10 of 10 endpoints

GET/browser/list

List windows

Pages through windows of the current team, including each window's bound proxy, platform accounts, and extensions, overlaid with local running and occupancy state.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
teamId	string | number	Optional	Team ID; defaults to the current team
page	number	Optional	Page number, default 1
size	number	Optional	Page size, default 20, server maximum 1000
keyword	string	Optional	Keyword, fuzzy-matches the window name
groupId	number	Optional	Omit to query all; 0 queries ungrouped; a positive number queries the given group; a negative number returns a parameter error

Notes

• opened is the open state recorded by the server and may hold a stale ON that this account did not release last time; to determine whether a window can be opened or is running locally, read runtimeState or effectiveOpened.
• runtimeState is computed with the same rules as the client buttons: occupancy by another user takes precedence, then whether there is a local running instance.

Response fields

Field	Type	Description
data.count	number	Total number of matching records
data.size	number	Page size, echoes the request value
data.page	number	Current page number, echoes the request value
data.total	number	Total number of pages
data.data	object[]	Records on the current page
data.data[].id	number	Window primary key ID; the windowId of window endpoints takes this value
data.data[].name	string	Window name
data.data[].userId	number	Owner user ID
data.data[].teamId	number	Owner team ID
data.data[].groupId	number	Window group ID, 0 means ungrouped
data.data[].seq	number	Sort value
data.data[].platformId	string	JSON text of the bound platform account ID array
data.data[].pluginId	string	JSON text of the installed extension ID array
data.data[].proxyId	number	Bound proxy ID, 0 means unbound
data.data[].remark	string	Window description
data.data[].uuid	string	Unique identifier of the window directory
data.data[].languageFrame	string	UI language, "0" means follow IP
data.data[].languageView	string	Web page language, auto/"0" means follow IP
data.data[].timezone	string	Time zone, auto/"0" means follow IP
data.data[].location	string	Latitude and longitude, comma-separated, "0,0" means follow IP
data.data[].locationAssable	number	Geolocation permission: 0 block, 1 ask, 2 allow
data.data[].audioSwitch	string	Audio toggle: ON, OFF
data.data[].pictureSwitch	string	Image toggle: ON, OFF
data.data[].videoSwitch	string	Video toggle: ON, OFF
data.data[].screenPixel	string	Resolution "width,height", "0,0" means full screen
data.data[].screenLocation	string	Window open position
data.data[].opened	string	Whether opened: ON, OFF
data.data[].openedUserId	number	ID of the user currently holding the open state
data.data[].activeAt	string	Last active time, null if never opened
data.data[].createdAt	string	Creation time, yyyy-MM-dd HH:mm:ss
data.data[].updatedAt	string	Update time, yyyy-MM-dd HH:mm:ss
data.data[].userEmail	string	Owner user email
data.data[].proxy	object	Bound proxy details, null if unbound; fields same as /proxy/list items
data.data[].platforms	object[]	Bound platform accounts, fields same as /account/list items (including plaintext passwords and 2FA secrets)
data.data[].plugins	object[]	Installed extensions
data.data[].effectiveOpened	string	Open state after overlaying local state: ON, OFF; ON when running locally or occupied by another user
data.data[].localRunning	boolean	Whether the window is running on this machine
data.data[].runtimeState	string	Runtime state: local_running running locally, occupied_by_other occupied by another user, closed not opened

Response example

{
  "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": [],
        "effectiveOpened": "OFF",
        "localRunning": false,
        "runtimeState": "closed"
      }
    ]
  }
}

POST/browser/create

Create browser window

Creates windows in batch using the defaults of the client's "Create window" dialog, requesting a separate fingerprint for each window.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
count	number	Optional	Number to create, default 1, at most 50 per request; exceeding it returns a business error directly
name	string	Optional	Window name; defaults to "环境-" (environment-) plus 5 digits; when count>1, sequence suffixes -01, -02 are appended automatically
groupId	number	Optional	Window group ID, 0 means ungrouped
remark	string	Optional	Window description
proxyId	number	Optional	Bound proxy ID, 0 means no binding
accountIds	number[] | string	Optional	Bound platform account IDs, an array or comma-separated text
pluginIds	string[] | string	Optional	Installed extension IDs, an array or comma-separated text
startupUrl	string	Optional	Window start page
screen	object	Optional	Window field overrides, keys same as /browser/list items
preference	object	Optional	Preference overrides
fingerprint	object	Optional	Fingerprint overrides; can specify osType, osVersion, coreVersion, etc.

Notes

• Fields that are not passed all use the client defaults.
• When all windows fail, the endpoint returns a business error, and msg summarizes the failure reasons row by row (server original text first, newline-separated).

Response fields

Field	Type	Description
data.rows	object[]	Per-window creation results
data.rows[].seq	number	Index within this batch, starting from 1
data.rows[].name	string	Window name actually used
data.rows[].success	boolean	Whether the window was created successfully
data.rows[].id	string	Window ID, returned on success
data.rows[].uuid	string	Unique identifier of the window directory, returned on success
data.rows[].error	string	Failure reason, omitted on success
data.rows[].code	string	Stable error code on failure, e.g. WINDOW_CREATE_FAILED; failures without a registered error code do not include this field
data.rows[].params	object	Interpolation parameters for the error code, returned only on some failed rows
data.success	number	Number of successful rows
data.failed	number	Number of failed rows
data.total	number	Total number of rows

Response example

{
  "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

Bind or unbind window proxy

Binds a proxy to one or more closed windows; proxyId 0 unbinds.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
windowIds	string[]	Required	One or more window IDs
proxyId	string | number	Required	Proxy ID; 0 removes the binding. Missing returns a parameter error

Notes

• When a window is open, its row fails with error "窗口正在运行，请关闭窗口后再修改代理" (the window is running; close it before changing the proxy); when all fail, the endpoint returns a business error with the errors summarized.
• Legacy alias: windowIds can also be written as windowId; a single value or an array is accepted.

Response fields

Field	Type	Description
data.rows	object[]	Per-window binding results
data.rows[].windowId	string	Window ID
data.rows[].proxyId	string | number	Proxy ID written this time
data.rows[].success	boolean	Whether the window was bound successfully
data.rows[].error	string	Failure reason, omitted on success
data.rows[].code	string	Stable error code on failure, e.g. WINDOW_RUNNING_PROXY_LOCKED, WINDOW_PROXY_BIND_FAILED
data.rows[].params	object	Interpolation parameters for the error code, returned only on some failed rows
data.success	number	Number of successful rows
data.failed	number	Number of failed rows
data.total	number	Total number of rows

Response example

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

POST/browser/account

Bind or unbind window platform accounts

Selects platform accounts for closed windows. Pass the account IDs to bind in `accountIds`; pass `[]` to select no account. This write replaces the existing bindings as a whole.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
windowIds	string[]	Required	One or more window IDs; windowId can also be used to pass a single ID or an ID array
accountIds	number[]	Required	Platform account ID list. Pass one or more account IDs to bind; pass [] to select no account. Missing returns a parameter error

Notes

• The platformId actually written to the window is JSON array text: the JSON text of accountIds when binding, "[]" when selecting no account.
• When the window is running, returns a business error "窗口正在运行，请关闭窗口后再修改平台账号" (the window is running; close it before changing platform accounts); when the write fails, msg prefers the server original text. On success, data is null.

Response fields

Field	Type	Description
data	null	No response data; success is indicated by code=0

Response example

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

POST/browser/group

Move windows to group

Moves one or more windows to the given window group; groupId 0 removes them from their group.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
windowIds	string[]	Required	One or more window IDs; windowId can also be used to pass a single ID or an ID array
groupId	string | number	Required	Target group ID; 0 removes from the group. Missing returns a parameter error

Notes

• Groups are only window metadata, so windows can be moved while open without closing them first.
• When all fail, the endpoint returns a business error with the errors summarized.

Response fields

Field	Type	Description
data.rows	object[]	Per-window move results
data.rows[].windowId	string	Window ID
data.rows[].groupId	number	Group ID written this time
data.rows[].success	boolean	Whether the window was moved successfully
data.rows[].error	string	Failure reason, omitted on success
data.rows[].code	string	Stable error code on failure, e.g. WINDOW_GROUP_MOVE_FAILED
data.rows[].params	object	Interpolation parameters for the error code, returned only on some failed rows
data.success	number	Number of successful rows
data.failed	number	Number of failed rows
data.total	number	Total number of rows

Response example

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

POST/browser/name

Rename window

Renames one window. Only the window ID and new name are accepted; no other window settings change.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
windowId	string | number	Required	ID of the window to rename
name	string	Required	New window name; leading and trailing spaces are trimmed. Blank returns a parameter error

Notes

• Only windowId and name are accepted; any other field returns a business error.
• The name is only window metadata, so windows can be renamed while open without closing them first.
• On a write failure, msg uses the server's original message, otherwise a generic rename failure message.

Response fields

Field	Type	Description
data.windowId	string	Window ID
data.name	string	Window name actually written

Response example

{
  "code": 0,
  "msg": "ok",
  "data": {
    "windowId": "8001",
    "name": "店铺 A"
  }
}

GET/browser/accounts

List fillable accounts for windows

Reads the accounts that can be auto-filled for sign-in in open windows, including bound platform accounts and passwords saved by the user. Usernames are masked; passwords and 2FA secrets never appear in the response.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
windowId	string | string[]	Required	Numeric window IDs; supports a single value, comma-separated text, or repeated parameters; window uuids are not accepted

Notes

• This endpoint is read-only and does not select accounts for windows. To select or deselect platform accounts, use POST /browser/account: pass accountIds to bind, or [] to select no account.
• Passwords and 2FA secrets are used only within the form-fill path of /automation/sessions/:sessionId/account_fill and are not sent out through this endpoint.
• Account entries also have a platformId field that is always an empty string; use platformUrl or platformName to identify the platform.

Response fields

Field	Type	Description
data	object[]	Per-window query results
data[].windowId	string	Window ID
data[].windowName	string	Window name, returned on success
data[].success	boolean	Whether the query for the window succeeded
data[].error	string	Failure reason, omitted on success
data[].code	string	Stable error code on failure; VAULT_SESSION_UNAVAILABLE when the window is not open or the vault session is unavailable
data[].accounts	object[]	Bound platform accounts (masked view)
data[].accounts[].accountId	string	Platform account ID
data[].accounts[].platformName	string	Platform name, derived from the platformUrl hostname
data[].accounts[].platformUrl	string	Platform site URL
data[].accounts[].username	string	Masked sign-in name
data[].accounts[].remark	string	Entry source, fixed Chinese: "平台账户" (platform account) or "自定义密码" (custom password)
data[].accounts[].hasPassword	boolean	Whether a password is stored
data[].accounts[].has2fa	boolean	Whether the 2FA secret can be used to generate codes

Response example

{
  "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

Open browser window

Launches one or more browser environments by window ID and makes a best effort to add CDP connection endpoints.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
teamId	string	Required	Current team ID; missing returns a business error
ids	string[]	Required	Array of window IDs

Notes

• When a single window is passed, data is that window object; when multiple windows are passed, data is the rows batch structure.
• If a local running instance already exists, it is reused directly and alreadyRunning=true is returned, without requesting server occupancy again.
• When the server records the window as open but there is no local running instance (occupied by another device or user, or not released by this account last time), the row fails with "重新打开失败：请刷新窗口列表后重试" (reopen failed; refresh the window list and try again); check runtimeState from /browser/list first.
• When the server returns already occupied by you (-1838), the window state is not automatically rolled back to closed.
• When teamId or window IDs are missing, returns a business error "请先在 AI Agent 中重新选择窗口，当前本地缺少窗口启动配置" (reselect the window in AI Agent first; the local window launch configuration is missing).
• If the window has launched but CDP endpoint resolution fails, the window is not rolled back; a cdpError field is added to that row instead.
• Legacy alias: ids can also be written as windowId or id; a single value or an array is accepted.

Response fields

Field	Type	Description
data.ok	boolean	Browser core launch result
data.id	string	Window ID
data.windowId	string	Window ID, same value as data.id
data.key	string	Local running instance identifier
data.profileDir	string	Window profile directory
data.running	boolean	Whether the window is running
data.success	boolean	Whether this row succeeded
data.alreadyRunning	boolean	Whether the window was already running before the call
data.actualKernelVersion	string	Browser core version actually used, null if it cannot be read
data.syncNotice	string	Profile sync notice (fixed Chinese text), returned only when launch produces a notice
data.syncNoticeCode	string	Stable notice code for syncNotice
data.ws	string	CDP WebSocket URL
data.cdpEndpoint	string	CDP WebSocket URL, same value as data.ws
data.http	string	CDP HTTP URL
data.cdpHttpEndpoint	string	CDP HTTP URL, same value as data.http
data.cdpPort	number	CDP port
data.devToolsActivePortPath	string	DevToolsActivePort file path
data.cdpError	string	Reason CDP endpoint resolution failed
data.rows	object[]	Per-row results when multiple windows are passed, fields as above
data.success	number	Number of successful rows
data.failed	number	Number of failed rows
data.total	number	Total number of rows

Response example

{
  "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

Browser connection info

Reads CDP connection info for running browsers; when no window is passed, returns all open windows.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
windowId	string | string[]	Optional	Window IDs; supports a single value, comma-separated text, or repeated parameters; omit to return all running windows

Notes

• Only running windows are returned; windows that are not running are filtered out; when no window is running, data is an empty array.

Response fields

Field	Type	Description
data	object[]	Connection info of running windows
data[].id	string	Window ID
data[].windowId	string	Window ID, same value as data[].id
data[].key	string	Local running instance identifier
data[].profileDir	string	Window profile directory
data[].running	boolean	Always true
data[].success	boolean	Always true
data[].ws	string	CDP WebSocket URL
data[].cdpEndpoint	string	CDP WebSocket URL, same value as data[].ws
data[].http	string	CDP HTTP URL
data[].cdpHttpEndpoint	string	CDP HTTP URL, same value as data[].http
data[].cdpPort	number	CDP port
data[].devToolsActivePortPath	string	DevToolsActivePort file path

Response example

{
  "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

Close browser window

Closes one or more running browser windows and returns batch results.

AuthBearer API Key

Request parameters

Field	Type	Required	Description
ids	string[]	Required	One or more window IDs; missing returns a business error
teamId	string	Optional	Optional team ID, used to release the window open state on the server

Notes

• Close waits for the window's exit profile sync to finish before returning; rows may also include per-stage statuses such as uploadStatus, releaseStatus, and pointerStatus.
• When the window was not running, its row returns success=false with error "Browser is not running: <id>".
• Legacy alias: ids can also be written as windowId or id; a single value or an array is accepted.

Response fields

Field	Type	Description
data.rows	object[]	Per-window close results
data.rows[].id	string	Window ID
data.rows[].key	string	Local running instance identifier
data.rows[].success	boolean	Whether the window was closed successfully
data.rows[].error	string	Failure reason, omitted on success
data.rows[].released	boolean	Whether the server window occupancy was released; returned when profile sync is enabled
data.rows[].syncStatus	string	Exit profile sync result: uploaded, skipped, blocked, failed; returned when profile sync is enabled
data.rows[].syncReason	string	Machine-readable reason when sync did not complete, e.g. upload-error
data.success	number	Number of successful rows
data.failed	number	Number of failed rows
data.total	number	Total number of rows

Response example

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