Browser Window Local API Documentation

Open Window

Title

Open Window

Brief Description

Open a browser window by window ID or window UUID.

Request URL

http://127.0.0.1:54345/browser/open

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "Browser opened",
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "browserId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "opened": true
  }
}

Success Response Parameter Descriptions

Notes

Only one window can be opened at a time. The interface only listens on 127.0.0.1; open and log in to the client before calling.

Close Window

Title

Close Window

Brief Description

Close a browser window by window ID or window UUID.

Request URL

http://127.0.0.1:54345/browser/close

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "Browser closed",
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "browserId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "opened": false,
    "close": true
  }
}

Success Response Parameter Descriptions

Notes

Only one window can be closed at a time. The interface only listens on 127.0.0.1; open and log in to the client before calling.

Create or Edit Window

Title

Create or Edit Window

Brief Description

When no window identifier is passed, a window is created; when an identifier is passed, the window is edited. When editing, config must be provided; first retrieve the current window configuration via /browser/detail and return it as-is.

Two creation modes are supported:

Invocation Mode Determination

If the request body contains a placeholder UUID like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, the Local API will treat it as an "edit window" request and may return {"code":211,"msg":"UUID invalid","data":{}}.

Request URL

http://127.0.0.1:54345/browser/update

Request Method

POST

Header

Request Body Parameters

Minimal Field Creation Request Example

{
  "name": "Local API minimal field window"
}

Full Configuration Creation Request Example

{
  "name": "Local API full config window",
  "group_id": 0,
  "config": {
    "browser_type": "firefox",
    "name": "Local API full config window",
    "browser_name": "Local API full config window",
    "group_id": 0,
    "proxy": {
      "type": "direct"
    },
    "fingerprint": {
      "noise_seed": "A1B2C3D4E5F60708",
      "canvas": { "mode": "on" },
      "audio_context": { "mode": "on" },
      "webgl_image": { "mode": "on" },
      "webgl_metadata": {
        "mode": "real",
        "vendor": "",
        "renderer": ""
      },
      "fonts": {
        "mode": "random",
        "font_list": [],
        "client_rects": true
      }
    },
    "navigator": {
      "user_agent": "",
      "cpu": { "mode": "custom", "value": 8 },
      "ram": { "mode": "custom", "value": 8 },
      "do_not_track": true
    },
    "webrtc": { "mode": "relay" },
    "geo": {
      "timezone": { "mode": "auto" },
      "geolocation": { "mode": "auto", "permission": "allow" },
      "language": { "mode": "auto", "values": [] }
    },
    "resolution": {
      "mode": "random",
      "width": 1920,
      "height": 1080
    },
    "cookies": { "mode": "merge", "items": [] },
    "launch_args": [],
    "extensions": [],
    "startup_pages": [],
    "raw": {
      "name": "Local API full config window",
      "browser_name": "Local API full config window",
      "group_id": 0,
      "proxy_method": "2",
      "proxy_type": "noproxy"
    }
  }
}

config Full Window Configuration Field Descriptions

When editing a window, it is recommended to first call /browser/detail to obtain data.config, modify the fields you need to change, and then pass it back as-is. The following tables are for understanding or manually constructing the full config object; different client/server versions may return additional extension fields – it is recommended to keep unrecognized fields.

#### config Top-Level Fields

#### config.cache_storage Cache Storage Configuration

#### config.proxy Proxy Configuration

#### config.fingerprint Fingerprint Low-Level Configuration

#### config.navigator Navigator and Device Info Configuration

#### config.webrtc, config.geo, config.resolution

#### config.cookies, config.credentials, config.syncConfig

#### Other Configuration Objects

#### config.raw Original Form Fields

raw is used to store original client form fields; recommended to keep when editing windows. Many fields map to config top-level, proxy, fingerprint.

#### raw.browserFingerPrint Form-Level Fingerprint Fields

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 10001,
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "Test window",
    "group_id": 0,
    "cache_storage_mode": "local"
  }
}

Success Response Parameter Descriptions

Create Window Request Example

{
  "name": "Test window",
  "group_id": 0,
  "remark": "Created by Local API",
  "cache_storage_mode": "local",
  "proxy_method": "2",
  "proxy_type": "noproxy"
}

Edit Window Request Example

Before editing, call /browser/list to get the real uuid, then /browser/detail to get data.config, and finally return the complete config as-is.

{
  "uuid": "real window UUID",
  "name": "New window name",
  "remark": "Edited by Local API",
  "cache_storage_mode": "local",
  "config": {
    "...": "put the complete data.config object from /browser/detail here"
  }
}

Postman Usage Tips

After importing LOCAL_API.postman_collection.json:

1. To create a window, use Browser / Create Browser and do not add uuid or id in the body.
2. To edit a window, first run Browser / List Browsers to get the real browser_uuid.
3. Then run Browser / Get Browser Detail and save browser_config.
4. Finally run Browser / Update Existing Browser - Requires Real UUID And Detail Config.

Notes

When creating a window with a proxy, pass fields like proxy_method, proxy_type, host, port according to proxy type. For no proxy, pass {"proxy_method":"2","proxy_type":"noproxy"}. Legacy fields proxyMethod / proxyType are still compatible.

Batch Create Windows

Title

Batch Create Windows

Brief Description

Batch create browser windows by quantity or a list of window configurations.

Batch creation also supports two modes:

Request URL

http://127.0.0.1:54345/browser/create/batch

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 2,
    "list": [
      {
        "id": 10001,
        "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1",
        "name": "Postman batch window-1"
      },
      {
        "id": 10002,
        "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2",
        "name": "Postman batch window-2"
      }
    ]
  }
}

Minimal Field Batch Creation by Count Request Example

{
  "create_count": 2,
  "name_prefix": "Postman batch window-"
}

Minimal Field Batch Creation by List Request Example

{
  "name_prefix": "Postman list window-",
  "items": [
    {
      "name": "Postman list window-1",
      "group_id": 0
    },
    {
      "name": "Postman list window-2",
      "group_id": 0,
      "browserFingerPrint": {
        "webRTC": "3",
        "resolutionType": "2"
      }
    }
  ]
}

Full Configuration Batch Creation by List Request Example

{
  "name_prefix": "Postman full config window-",
  "items": [
    {
      "name": "Postman full config window-1",
      "group_id": 0,
      "config": {
        "browser_type": "firefox",
        "name": "Postman full config window-1",
        "browser_name": "Postman full config window-1",
        "group_id": 0,
        "proxy": { "type": "direct" },
        "fingerprint": {
          "noise_seed": "A1B2C3D4E5F60708",
          "canvas": { "mode": "on" },
          "audio_context": { "mode": "on" },
          "webgl_image": { "mode": "on" },
          "webgl_metadata": {
            "mode": "real",
            "vendor": "",
            "renderer": ""
          },
          "fonts": {
            "mode": "random",
            "font_list": [],
            "client_rects": true
          }
        },
        "navigator": {
          "user_agent": "",
          "cpu": { "mode": "custom", "value": 8 },
          "ram": { "mode": "custom", "value": 8 }
        },
        "webrtc": { "mode": "relay" },
        "geo": {
          "timezone": { "mode": "auto" },
          "geolocation": { "mode": "auto", "permission": "allow" },
          "language": { "mode": "auto", "values": [] }
        },
        "resolution": { "mode": "random" },
        "cookies": { "mode": "merge", "items": [] },
        "raw": {
          "name": "Postman full config window-1",
          "browser_name": "Postman full config window-1",
          "group_id": 0,
          "proxy_method": "2",
          "proxy_type": "noproxy"
        }
      }
    }
  ]
}

Common Errors

If creating with items returns {"code":211,"msg":"name prefix required","data":{}}, add name_prefix at the top level of the request body, not just in items[].name.

Success Response Parameter Descriptions

Notes

Equivalent paths also available: /browser/batch-create, /browser/createBatch. To create in a specific group with tags, first call group and tag list endpoints to get real IDs. When proxy_method / proxy_type are not passed, Local API defaults to proxy_method=2, proxy_type=noproxy. create_count is suitable when all windows share the same top-level parameters; for per-window full customization, use items[].config.

Batch Update Window Configurations

Title

Batch Update Window Configurations

Brief Description

Batch modify configuration fields of multiple windows, can also synchronize group, tags, or remark.

Request URL

http://127.0.0.1:54345/browser/update/partial

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001, 10002],
    "updated": 2
  }
}

Success Response Parameter Descriptions

Notes

Example config: {"config":{"syncCookies":true,"browserFingerPrint":{"webRTC":"3"}},"configFields":["syncCookies","browserFingerPrint.webRTC"]}. To batch update only remarks, pass {"ids":[10001],"remark":"new remark"}.

Query Window List

Title

Query Window List

Brief Description

Paginated window list query, supports filtering by group, name, remark, and status.

Request URL

http://127.0.0.1:54345/browser/list

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 10001,
        "backend_id": 10001,
        "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "name": "Test window",
        "group_id": 0,
        "remark": "Created by Local API",
        "cache_storage_mode": "local"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

Success Response Parameter Descriptions

Notes

Local API by default sends lite=1 to the cloud list, so lightweight list does not return full config. When editing, copying, or viewing full configuration, call /browser/detail again. Return fields may increase with server version. For batch modifying window group, remark, or proxy, prefer using backend_id / browserId from the list response as ids.

Query Window Detail

Title

Query Window Detail

Brief Description

Query window details by window UUID or window ID.

Request URL

http://127.0.0.1:54345/browser/detail

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 10001,
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "Test window",
    "group_id": 0,
    "remark": "Created by Local API",
    "cache_storage_mode": "local",
    "config": {}
  }
}

Success Response Parameter Descriptions

Notes

It is recommended to use uuid for detail queries; if only numeric ID is provided, Local API will first resolve the list to find the corresponding UUID.

Delete Window

Title

Delete Window

Brief Description

Delete one or multiple windows.

Request URL

http://127.0.0.1:54345/browser/delete

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001]
  }
}

Success Response Parameter Descriptions

Notes

This endpoint moves windows to recycle bin / performs deletion logic, specific behavior depends on current client and server configuration.

Batch Delete Windows

Title

Batch Delete Windows

Brief Description

Batch delete windows by array of window IDs.

Request URL

http://127.0.0.1:54345/browser/delete/ids

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001, 10002]
  }
}

Success Response Parameter Descriptions

Notes

To delete a single window, you can also use /browser/delete.

Batch Update Window Group

Title

Batch Update Window Group

Brief Description

Move multiple windows to a specified group.

Request URL

http://127.0.0.1:54345/browser/group/update

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001, 10002],
    "group_id": 123
  }
}

Success Response Parameter Descriptions

Notes

When fetching window identifiers from /browser/list, prefer using backend_id / browserId in the response as ids; if only uuid / config_uuid is available, pass uuids.

Batch Update Window Remark

Title

Batch Update Window Remark

Brief Description

Batch modify the remark of multiple windows.

Request URL

http://127.0.0.1:54345/browser/remark/update

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001, 10002],
    "remark": "Batch remark"
  }
}

Success Response Parameter Descriptions

Notes

When fetching window identifiers from /browser/list, prefer using backend_id / browserId as ids; if only uuid / config_uuid is available, pass uuids.

Query Proxy List

Title

Query Proxy List

Brief Description

Paginated query of proxies from proxy IP management, supports filtering by name, proxy method, proxy type, owning user, region, and check status.

Request URL

http://127.0.0.1:54345/proxy/list

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "proxy_name": "Test proxy",
        "proxy_method": "custom",
        "proxy_type": "http",
        "host": "127.0.0.1",
        "port": 7890,
        "username": "",
        "country": "CN",
        "region": "Shanghai",
        "check_status": 1
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

Success Response Parameter Descriptions

Notes

This endpoint forwards locally to backend /api/browser/proxies/list. Local paths /browser/proxy/list and /browser/proxies/list are also compatible. Return fields may increase with server version.

Batch Update Window Proxy

Title

Batch Update Window Proxy

Brief Description

Batch modify proxy configuration for multiple windows.

Request URL

http://127.0.0.1:54345/browser/proxy/update

Request Method

POST

Header

Request Body Parameters

Success Response Example

{
  "code": 0,
  "msg": "success",
  "data": {
    "ids": [10001, 10002],
    "proxy_method": "2",
    "proxy_type": "noproxy"
  }
}

Success Response Parameter Descriptions

Notes

When fetching window identifiers from /browser/list, prefer using backend_id / browserId as ids; if only uuid / config_uuid is available, pass uuids. For no proxy, pass: {"proxy_method":"2","proxy_type":"noproxy"}.