Browser Window API

This document explains the browser window API. Cloud APIs handle CRUD operations for window configurations, while the local Local API is used to open and close browser windows, and can also forward some cloud API requests.

API Description

• All requests use the POST method.
• Request parameters are sent as JSON body.
• For cloud APIs, we recommend passing the login state via Authorization: Bearer {auth}.
• The Local API only listens on 127.0.0.1, with the default port 54345. The actual port and access token are displayed on the client's "System Settings / Local API" page.
• The Local API uses X-Cos-Local-Token to pass the local access token and requires the client to be logged in.
• The response format is unified as code/msg/data.
• page starts from 0, where 0 represents the first page.
• Deleting a window moves it to the recycle bin during the first phase by default.

Cloud API unified request headers:

Content-Type: application/json
Authorization: Bearer {auth}

Local API unified request headers:

Content-Type: application/json
X-Cos-Local-Token: <local access token>

Unified response:

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

Common Local API status codes:

Create Browser Window

POST /browser/update

If id, browserId, or uuid is not provided, it means creating a window.

Request Example

{
  "name": "windows browser",
  "groupId": 12,
  "tagIds": [3, 5],
  "remark": "Created via API",
  "proxyMethod": 2,
  "proxyType": "socks5",
  "host": "1.2.3.4",
  "port": 1020,
  "proxyUserName": "abc",
  "proxyPassword": "def",
  "browserFingerPrint": {
    "coreVersion": "118",
    "ostype": "PC",
    "os": "Win32"
  }
}

Parameter Details

Local API Notes

When creating a window via the Local API, the config field is actually required and cannot be omitted or left as an empty object {}. Otherwise, the following response is returned:

{
  "code": 211,
  "msg": "Configuration must be a JSON object",
  "data": {}
}

If creating a window through Local API, pass a complete non-empty config object; for simple parameter-based creation, it is recommended to call the cloud API directly.

Permission

Requires browser:create:single.

Edit Browser Window

POST /browser/update

Passing id, browserId, or uuid indicates editing a window.

Request Example

{
  "id": 101,
  "name": "Modified window name",
  "groupId": 15,
  "remark": "Modified remark",
  "tagIds": [3, 8]
}

Local API Notes

When editing a window via the Local API, /browser/update also requires a complete config object. If you only need to modify metadata like name, group, remark, or tags, it's recommended to use /browser/update/partial instead.

Permission

Requires browser:update:single.

Update Specific Window Fields with Batch Support

POST /browser/update/partial

Send only the fields that need updating.

For proxy changes, prefer using /browser/proxy/update.

Request Example

{
  "ids": [101, 102],
  "name": "Batch renamed",
  "groupId": 15,
  "remark": "New remark",
  "tagIds": [3, 8]
}

Parameter Details

Permission

• Single window: browser:update:single
• Multiple windows: browser:update:batch

Get Browser Window Details

POST /browser/detail

Request Example

{
  "id": 101
}

Alternatively:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Parameter Details

At least one of id, browserId, or uuid must be provided.

Local API Notes

• When querying details via Local API, using a numeric id may return code: 211, msg: "UUID invalid".
• If id, browserId, or uuid is missing, Local API may also return msg: "UUID invalid"; callers should validate parameters beforehand.
• For Local API compatibility, prefer passing uuid.

Permission

Requires browser:list.

Paginated Browser Window List

POST /browser/list

Request Example

{
  "page": 0,
  "pageSize": 20,
  "groupId": 12
}

Parameter Details

Permission

Requires browser:list.

Delete Browser Window

POST /browser/delete

First-phase deletion moves the window to the recycle bin by default.

Request Example

{
  "id": 101
}

Parameter Details

Permission

Requires browser:delete:recycle.

Batch Delete Browser Windows

POST /browser/delete/ids

Request Example

{
  "ids": [101, 102]
}

Permission

Requires browser:delete:recycle.

Batch Update Browser Window Group

POST /browser/group/update

Request Example

{
  "ids": [101, 102],
  "groupId": 15
}

Parameter Details

Permission

• Single window: browser:update:single
• Multiple windows: browser:update:batch

Batch Update Window Remarks

POST /browser/remark/update

Request Example

{
  "ids": [101, 102],
  "remark": "Remark info"
}

Parameter Details

Permission

• Single window: browser:update:single
• Multiple windows: browser:update:batch

Batch Update Window Proxy Settings

POST /browser/proxy/update

Sets the same proxy configuration for multiple windows in batch.

Request Example

{
  "ids": [101, 102],
  "ipCheckService": "ip-api",
  "proxyMethod": 2,
  "proxyType": "socks5",
  "host": "127.0.0.1",
  "port": 1080,
  "proxyUserName": "user",
  "proxyPassword": "pass",
  "refreshProxyUrl": ""
}

Parameter Details

Notes:

• Only saves cloud configuration in the first phase.
• Does not open the browser.
• Does not check local ports.
• Does not read runtime cookies.

Permission

• Single window: browser:update:single
• Multiple windows: browser:update:batch

Open Browser Window

POST /browser/open

This endpoint is part of the Local API and opens a browser window. Full request URL example:

POST http://127.0.0.1:54345/browser/open

Request Example

{
  "uuid": "browser-config-uuid"
}

Parameter Details

This endpoint supports opening only one window at a time. Passing multiple ids or uuids will return code: 211.

Success Response Example

{
  "code": 0,
  "msg": "Browser opened",
  "data": {
    "id": "123",
    "browserId": "123",
    "uuid": "browser-config-uuid",
    "pid": 45678,
    "alreadyStarted": false,
    "profileDir": "C:\\Users\\...\\browser-cache\\firefox-profiles\\...",
    "configPath": "C:\\Users\\...\\firefox-launch-configs\\browser-config-uuid.json",
    "openedStatus": {
      "beforeStart": {},
      "afterStart": {}
    }
  }
}

Execution Behavior

The API performs the following steps for the currently logged-in account:

1. Read window details.
2. Call the server launch endpoint to obtain launch configuration.
3. Parse proxy configuration; if the window uses API proxy extraction, it fetches the extraction URL first.
4. Prepare local Firefox profile directory.
5. Start the Firefox browser window.
6. Sync open status with the server.

Permission

Requires the client to be logged in and provide a valid X-Cos-Local-Token.

Close Browser Window

POST /browser/close

This endpoint is part of the Local API and closes an already open browser window. Full request URL example:

POST http://127.0.0.1:54345/browser/close

Request Example

{
  "uuid": "browser-config-uuid"
}

Parameter Details

This endpoint supports closing only one window at a time. Passing multiple ids or uuids will return code: 211.

Success Response Example

{
  "code": 0,
  "msg": "Browser closed",
  "data": {
    "id": "123",
    "browserId": "123",
    "uuid": "browser-config-uuid",
    "close": {
      "error": 0,
      "killed": false,
      "profileZipPath": "C:\\Users\\...\\uploaded-profile-zips\\browser-config-uuid.zip",
      "profileZipName": "browser-config-uuid.zip",
      "profileZipSize": 102400
    },
    "cookies": {},
    "backendClose": {},
    "openedStatus": {
      "beforeClose": {},
      "afterClose": {}
    }
  }
}

Execution Behavior

The API performs the following steps for the currently logged-in account:

1. Read window details.
2. Update server open status to "closing".
3. Close the local Firefox process.
4. Package local profile data according to window sync configuration.
5. If the window has syncCookies enabled, attempt to read Firefox exported cookies and sync them to server configuration.
6. Call the server close endpoint.
7. Update server open status to "closed".

The close response includes local profile ZIP information in data.close. The current Local API does not execute additional frontend official/custom cache upload pipelines.

Permission

Requires the client to be logged in and provide a valid X-Cos-Local-Token.

Local Runtime APIs Not Covered in This Document

The following APIs depend on local browser processes, debugging ports, or automation environments and are not expanded here: