Local API

https://localapi-doc-zh.adspower.net/docs
Admin
An API for programmatic control and management of browser environments, groups, and proxy settings.
Tokens:53,380
Snippets:159
Trust Score:9.8
Update:10 months ago
Show doc for...
Tokens:
Raw
### GET /api/v1/browser/start

Source: https://localapi-doc-zh.adspower.net/docs/Exqfpw

Starts a browser instance. You need to specify the environment ID. After a successful start, you can get the browser's debug interface for Selenium and Puppeteer automation. Selenium requires a matching Webdriver for the corresponding kernel version. This feature requires application version 3.4.1 or above. The path to the Webdriver will be returned in the response.

```APIDOC
## GET /api/v1/browser/start

### Description
Starts a browser instance and provides debug endpoints for automation.

### Method
GET

### Endpoint
/api/v1/browser/start

### Parameters
#### Query Parameters
- **user_id** (string) - Required - The unique ID of the environment, generated upon successful environment creation.
- **serial_number** (string) - Optional - The environment number. If environment ID is provided, it takes precedence.
- **open_tabs** (integer) - Optional - Whether to open platform and history pages. 0: Open (default), 1: Do not open. Requires version V2.4.2.9 or above.
- **ip_tab** (integer) - Optional - Whether to open the IP detection page. 0: Do not open, 1: Open (default). Requires version V2.5.7.9 or above.
- **new_first_tab** (integer) - Optional - Whether to use the new IP detection page. 1: New version, 0: Old version (default). Requires version V2.6.6.9 or above.
- **launch_args** (array of strings) - Optional - Launch arguments, e.g., `["--window-position=400,0", "--blink-settings=imagesEnabled=false", "--disable-notifications"]`. If `launch_args` are provided via the API, they will take precedence. Requires version V2.4.6.7 or above.
- **headless** (integer) - Optional - Whether to start a headless browser. 0: No (default), 1: Yes. Requires version V2.4.6.7 or above.
- **disable_password_filling** (integer) - Optional - Whether to disable the account/password filling feature. 0: No (default), 1: Yes. Requires version V2.4.6.7 or above.
- **clear_cache_after_closing** (integer) - Optional - Whether to clear cache after closing the browser. 0: No (default), 1: Yes. Requires version V2.4.7.6 or above. Recommended to set to 1 if disk space is insufficient.
- **enable_password_saving** (integer) - Optional - Whether to allow password saving. 0: No (default), 1: Yes. Requires version V2.4.8.7 or above.
- **cdp_mask** (integer) - Optional - Whether to mask CDP detection. 1: Yes (default), 0: No. Requires version V2.7.0.2 or above. Force enabled for iOS and Android.
- **device_scale** (number) - Optional - Valid for mobile mode. Range from 0.1 to 2. A value of 1 means 100%. Requires version v2.7.3.8 or above. Only effective for Chrome kernel 128 and above on Android and iOS.

### Request Example
```
GET /api/v1/browser/start?user_id=h1yynkm&open_tabs=1
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success, -1 for failure.
- **data** (object) - Contains browser debug information.
  - **ws** (object) - WebSocket endpoints for automation.
    - **selenium** (string) - Browser debug interface for Selenium automation.
    - **puppeteer** (string) - Browser debug interface for Puppeteer automation.
  - **debug_port** (string) - The debug port number.
  - **webdriver** (string) - The path to the WebDriver executable.
- **msg** (string) - Success or failure message.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "ws": {
      "selenium": "127.0.0.1:xxxx",
      "puppeteer": "ws://127.0.0.1:xxxx/devtools/browser/xxxxxx"
    },
    "debug_port": "xxxx",
    "webdriver": "C:\\xxxx\\chromedriver.exe"
  },
  "msg": "success"
}
```

#### Error Response (e.g., 400 or other non-200 codes)
```json
{
  "code": -1,
  "data": {},
  "msg": "failed"
}
```
```

--------------------------------

### Java Selenium Example

Source: https://localapi-doc-zh.adspower.net/docs/uYdU0j

This example shows how to start and control a browser instance using AdsPower API with Java Selenium.

```APIDOC
## GET /api/v1/browser/start & POST /api/v1/browser/stop (Java Selenium)

### Description
This Java code snippet demonstrates how to use the AdsPower API to start a browser instance with Selenium WebDriver and then close it.

### Method
GET (for start), POST (for stop)

### Endpoint
- Start: `/api/v1/browser/start?user_id={user_id}`
- Stop: `/api/v1/browser/stop?user_id={user_id}`

### Parameters
#### Query Parameters (for both start and stop endpoints)
- **user_id** (string) - Required - The ID of the AdsPower user profile to start or stop.

#### Headers (for both start and stop endpoints)
- **Authorization** (string) - Required - Bearer token for authentication. Example: `Bearer your_api_key_here`

### Request Example (Java)
```java
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

public class AdsDemo {
    WebDriver driver;

    private String apiKey = "your_api_key_here"; // Define API Key as token
    private String adsId = "xxxx"; // Specify the user ID

    private WebDriver getDriver() {
        try {
            // Construct the URL to start the browser
            String openUrl = "http://local.adspower.net:50325/api/v1/browser/start?user_id=" + adsId;

            // Send HTTP GET request with Authorization Bearer Token
            JsonObject result = makeHttpRequest(openUrl);

            // Check response status
            if (result.get("code").getAsInt() != 0) {
                System.out.println("Error: " + result.get("msg").getAsString());
                System.out.println("Please check ads_id");
                return null;
            }

            // Get the returned data
            JsonObject data = result.getAsJsonObject("data");
            String chromeDriver = data.get("webdriver").getAsString();
            String debuggerAddress = data.getAsJsonObject("ws").get("selenium").getAsString();

            // Set webdriver path
            System.setProperty("webdriver.chrome.driver", chromeDriver);

            // Configure Chrome options
            ChromeOptions options = new ChromeOptions();
            options.setExperimentalOption("debuggerAddress", debuggerAddress);

            // Create WebDriver instance
            driver = new ChromeDriver(options);
            driver.get("https://www.browserscan.net/");

            return driver;
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }

    private JsonObject makeHttpRequest(String url) throws Exception {
        // Create HTTP client
        HttpClient client = HttpClient.newHttpClient();

        // Build request, add Authorization Bearer Token header
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "Bearer " + apiKey)
                .GET()
                .build();
        // Send request and get response
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        // Parse JSON response
        return JsonParser.parseString(response.body()).getAsJsonObject();
    }

    public void closeBrowser() {
        try {
            if (driver != null) {
                driver.quit();
            }
            // API request to stop the browser
            String closeUrl = "http://local.adspower.net:50325/api/v1/browser/stop?user_id=" + adsId;
            makeHttpRequest(closeUrl);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static void main(String[] args) {
        AdsDemo demo = new AdsDemo();
        WebDriver driver = demo.getDriver();

        if (driver != null) {
            System.out.println("Browser started successfully!");
            System.out.println("Title: " + driver.getTitle());

            // Wait for user input before closing
            System.out.println("Press Enter to close browser...");
            try {
                System.in.read();
            } catch (Exception e) {
                e.printStackTrace();
            }
            demo.closeBrowser();
        }
    }
}
```

### Response
#### Success Response (200)
- **code** (integer) - Status code, 0 indicates success.
- **msg** (string) - Message describing the result.
- **data** (object) - Contains browser connection details.
  - **webdriver** (string) - URL for WebDriver connection.
  - **ws** (object) - WebSocket information.
    - **puppeteer** (string) - WebSocket endpoint for Playwright.
    - **selenium** (string) - WebSocket endpoint for Selenium.

#### Response Example (from /api/v1/browser/start)
```json
{
    "code": 0,
    "msg": "",
    "data": {
        "browser_type": "chrome",
        "webdriver": "http://127.0.0.1:9999/wd/hub",
        "ws": {
            "puppeteer": "ws://127.0.0.1:9999/devtools/page/some-page-guid",
            "selenium": "ws://127.0.0.1:9999/devtools/page/some-page-guid"
        },
        "user_id": "xxxx"
    }
}
```

#### Response Example (from /api/v1/browser/stop)
```json
{
    "code": 0,
    "msg": "success"
}
```
```

--------------------------------

### Example Fingerprint Configuration JSON

Source: https://localapi-doc-zh.adspower.net/docs/BgoAbq

An example of a JSON object for configuring browser fingerprinting. This includes settings for automatic timezone, language preferences, user agent string, flash status, and WebRTC.

```json
{
"automatic_timezone": "1",
"language": ["en-US","en","zh-CN","zh"],
"ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.141",
"flash": "block",
"webrtc": "disabled"
}
```

--------------------------------

### Start Browser V2

Source: https://localapi-doc-zh.adspower.net/docs/qi-dong-liu-lan-qi-V2

Starts a browser instance with specified environment ID and configuration. It returns debugging interfaces for Selenium and Puppeteer automation, along with the WebDriver path.

```APIDOC
## POST /api/v2/browser-profile/start

### Description
Used to start a browser. Requires an environment ID. Upon successful startup, it provides browser debug interfaces for executing Selenium and Puppeteer automation. Selenium requires a WebDriver matching the kernel version. Ensure your application version is 3.4.1 or above. The corresponding WebDriver path can be obtained from the return value after starting the browser.

### Method
POST

### Endpoint
/api/v2/browser-profile/start

### Parameters
#### Request Body
- **profile_id** (text) - Required - Environment ID, a unique ID generated after successful environment creation.
- **profile_no** (text) - Optional - Environment number. If environment ID is provided, it takes precedence.
- **launch_args** (list) - Optional - Launch arguments. If `launch_args` are provided in the API call, they will be used.
- **headless** (text) - Optional - Default: `0`. Set to `1` to start a headless browser, `0` for a non-headless browser (default).
- **last_opened_tabs** (text) - Optional - Default: `1`. Set to `1` to continue browsing previously opened tabs (default), `0` to not.
- **proxy_detection** (text) - Optional - Default: `1`. Set to `1` to enable proxy detection page (default), `0` to disable.
- **password_filling** (text) - Optional - Default: `0`. Set to `1` to enable password filling functionality, `0` to disable (default). Only effective when the environment is opened for the first time.
- **password_saving** (text) - Optional - Default: `0`. Set to `1` to allow saving passwords, `0` to not allow (default). Only effective for Chrome kernel.
- **cdp_mask** (text) - Optional - Default: `1`. Set to `1` to mask CDP detection (default), `0` to not. Forced enabled on iOS and Android.
- **delete_cache** (text) - Optional - Default: `0`. Set to `1` to clear cache after closing the browser (default), `0` to not. If disk space is insufficient, it is recommended to set this parameter to `1`.
- **device_scale** (text) - Optional - Scale ratio for mobile mode, value range is 0.1-2. `1` means 100%. Only effective for Chrome kernel 128 and above on Android and iOS.

### Request Example
```json
{
  "profile_id": "h1yynkm",
  "profile_no": "123",
  "launch_args": [
    "--window-position=400,0",
    "--blink-settings=imagesEnabled=false",
    "--disable-notifications"
  ],
  "headless": "0",
  "last_opened_tabs": "1",
  "proxy_detection": "1",
  "password_filling": "0",
  "password_saving": "0",
  "cdp_mask": "1",
  "delete_cache": "0",
  "device_scale": "1"
}
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success, -1 for failure.
- **data** (object) - Contains browser details if successful.
  - **ws** (object) - Browser debug interfaces.
    - **selenium** (string) - Debug interface for Selenium automation.
    - **puppeteer** (string) - Debug interface for Puppeteer automation.
  - **debug_port** (string) - The debug port number.
  - **webdriver** (string) - The path to the WebDriver executable.
- **msg** (string) - Success or failure message.

#### Response Example
```json
{
  "code": 0,
  "data": {
    "ws": {
      "selenium": "127.0.0.1:xxxx",
      "puppeteer": "ws://127.0.0.1:xxxx/devtools/browser/xxxxxx"
    },
    "debug_port": "xxxx",
    "webdriver": "C:\\xxxx\\chromedriver.exe"
  },
  "msg": "success"
}
```

#### Error Response (Non-200)
```json
{
  "code": -1,
  "data": {},
  "msg": "failed"
}
```
```

--------------------------------

### User Proxy Configuration JSON Examples for AdsPower

Source: https://localapi-doc-zh.adspower.net/docs/SzqA0A

This snippet provides example JSON objects for configuring different proxy services within AdsPower. Each example includes the 'proxy_soft' and other relevant parameters such as 'proxy_type', 'proxy_host', 'proxy_port', 'proxy_user', and 'proxy_password'. Specific proxy types and their supported protocols are also indicated.

```json
{
  "proxy_soft": "brightdata",
  "proxy_type": "http",
  "proxy_host": "xxxx",
  "proxy_port": "xx",
  "proxy_user": "xxx",
  "proxy_password": "**"
}
```

```json
{
  "proxy_soft": "brightauto",
  "proxy_type": "http",
  "proxy_host": "xxxx",
  "proxy_port": "xx",
  "proxy_user": "xxx",
  "proxy_password": "**"
}
```

```json
{
  "proxy_soft": "oxylabsauto",
  "proxy_type": "http",
  "proxy_host": "xxxx",
  "proxy_port": "xx",
  "proxy_user": "xx",
  "proxy_password": "**"
}
```

```json
{
  "proxy_soft": "ipideaauto",
  "proxy_type": "http",
  "proxy_host": "xxxx",
  "proxy_port": "xx",
  "proxy_user": "xx",
  "proxy_password": "**"
}
```

```json
{
  "proxy_soft": "ipfoxyauto",
  "proxy_type": "http",
  "proxy_host": "xxxx",
  "proxy_port": "xx",
  "proxy_user": "xx",
  "proxy_password": "**"
}
```

```json
{
  "proxy_soft": "922S5auth",
  "proxy_type": "http",
  "proxy_host": "xxxx",
  "proxy_port": "xx",
  "proxy_user": "xx",
  "proxy_password": "**"
}
```

```json
{
  "proxy_soft": "kookauto",
  "proxy_type": "http",
  "proxy_host": "xxxx",
  "proxy_port": "xx",
  "proxy_user": "xx",
  "proxy_password": "**"
}
```

```json
{
  "proxy_soft": "lumiproxyauto",
  "proxy_type": "http",
  "proxy_host": "xxxx", 
  "proxy_port": "xx",
  "proxy_user": "xx",
  "proxy_password": "**"
}
```

```json
{
  "proxy_soft": "922S5auto"
}
```

```json
{
  "proxy_soft": "other",
  "proxy_type": "socks5",
  "proxy_host": "xxxx",
  "proxy_port": "xx",
  "proxy_user": "xxx",
  "proxy_password": "**"
}
```

```json
{
  "proxy_soft": "no_proxy"
}
```

--------------------------------

### Response Example: Browser Active Status (JSON)

Source: https://localapi-doc-zh.adspower.net/docs/SWZF3h

Example JSON response for a successful query of browser startup status. It indicates the browser is 'Active' and provides WebSocket endpoints for Selenium and Puppeteer automation.

```json
{
  "code": 0,
  "data": {
    "status": "Active",
    "ws": {
      "selenium": "127.0.0.1:xxxx",
      "puppeteer": "ws://127.0.0.1:xxxx/devtools/browser/xxxxxx"
    }
  },
  "msg": "success"
}
```

--------------------------------

### Javascript Playwright Example

Source: https://localapi-doc-zh.adspower.net/docs/uYdU0j

This example demonstrates how to start a browser instance using AdsPower API with Playwright and navigate to a webpage.

```APIDOC
## GET /api/v1/browser/start

### Description
Starts a browser instance managed by AdsPower.

### Method
GET

### Endpoint
`/api/v1/browser/start?user_id={user_id}`

### Parameters
#### Query Parameters
- **user_id** (string) - Required - The ID of the AdsPower user profile to start.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication. Example: `Bearer your_api_key_here`

### Request Example
```javascript
const axios = require('axios');
const { chromium } = require('playwright');

const apiKey = 'your_api_key_here'; // Define API Key as token
const userId = 'xxx'; // Specify the user ID

axios.get(`http://local.adspower.net:50325/api/v1/browser/start?user_id=${userId}`, {
    headers: {
        'Authorization': `Bearer ${apiKey}`
    }
}).then(async (res) => {
    console.log(res.data);
    if (res.data.code === 0 && res.data.data.ws && res.data.data.ws.puppeteer) {
        try {
            const browser = await chromium.connectOverCDP(res.data.data.ws.puppeteer);
            const defaultContext = browser.contexts()[0];
            const page = await defaultContext.newPage();
            await page.goto('https://www.browserscan.net');
            // To close the browser later, you would typically use a POST request to /api/v1/browser/stop
        } catch (err) {
            console.log(err.message);
        }
    }
}).catch((err) => {
    console.log(err);
});
```

### Response
#### Success Response (200)
- **code** (integer) - Status code, 0 indicates success.
- **msg** (string) - Message describing the result.
- **data** (object) - Contains browser connection details.
  - **webdriver** (string) - URL for WebDriver connection.
  - **ws** (object) - WebSocket information.
    - **puppeteer** (string) - WebSocket endpoint for Playwright.
    - **selenium** (string) - WebSocket endpoint for Selenium.

#### Response Example
```json
{
    "code": 0,
    "msg": "",
    "data": {
        "browser_type": "chrome",
        "webdriver": "http://127.0.0.1:9999/devtools/browser/some-guid",
        "ws": {
            "puppeteer": "ws://127.0.0.1:9999/devtools/page/some-page-guid",
            "selenium": "ws://127.0.0.1:9999/devtools/page/some-page-guid"
        },
        "user_id": "xxx"
    }
}
```

## POST /api/v1/browser/stop

### Description
Stops a browser instance managed by AdsPower.

### Method
POST

### Endpoint
`/api/v1/browser/stop?user_id={user_id}`

### Parameters
#### Query Parameters
- **user_id** (string) - Required - The ID of the AdsPower user profile to stop.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication. Example: `Bearer your_api_key_here`

### Request Example
```javascript
// This would typically be called after the browser session is finished.
// Example using axios:
axios.post(`http://local.adspower.net:50325/api/v1/browser/stop?user_id=${userId}`, null, {
    headers: {
        'Authorization': `Bearer ${apiKey}`
    }
}).then(response => {
    console.log('Browser stopped:', response.data);
}).catch(error => {
    console.error('Error stopping browser:', error);
});
```

### Response
#### Success Response (200)
- **code** (integer) - Status code, 0 indicates success.
- **msg** (string) - Message describing the result.

#### Response Example
```json
{
    "code": 0,
    "msg": "success"
}
```
```

--------------------------------

### Start and Stop Browser Instance

Source: https://localapi-doc-zh.adspower.net/docs/uYdU0j

This section details how to start and stop a browser instance using the AdsPower Local API with Python Selenium. It includes authentication, request examples, and response handling.

```APIDOC
## POST /api/v1/browser/start

### Description
Starts a new browser instance managed by AdsPower.

### Method
GET

### Endpoint
`/api/v1/browser/start?user_id={ads_id}`

### Parameters
#### Query Parameters
- **user_id** (string) - Required - The ID of the AdsPower browser profile to start.

#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication. Example: `Bearer your_api_key_here`

### Request Example
```python
import requests

ads_id = "xxx"
apiKey = "your_api_key_here"
open_url = "http://local.adspower.com:50325/api/v1/browser/start?user_id=" + ads_id
headers = {
    'Authorization': f'Bearer {apiKey}'
}
resp = requests.get(open_url, headers=headers).json()
print(resp)
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **msg** (string) - Success message.
- **data** (object) - Contains browser control data.
  - **webdriver** (string) - Path to the WebDriver executable.
  - **marionette_port** (string) - Port for the WebDriver connection.

#### Response Example
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "webdriver": "/path/to/chromedriver",
        "marionette_port": "12345"
    }
}
```

## GET /api/v1/browser/stop

### Description
Stops an existing browser instance managed by AdsPower.

### Method
GET

### Endpoint
`/api/v1/browser/stop?user_id={ads_id}`

### Parameters
#### Query Parameters
- **user_id** (string) - Required - The ID of the AdsPower browser profile to stop.

#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication. Example: `Bearer your_api_key_here`

### Request Example
```python
import requests

ads_id = "xxx"
apiKey = "your_api_key_here"
close_url = "http://local.adspower.com:50325/api/v1/browser/stop?user_id=" + ads_id
headers = {
    'Authorization': f'Bearer {apiKey}'
}
resp = requests.get(close_url, headers=headers).json()
print(resp)
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **msg** (string) - Success message.

#### Response Example
```json
{
    "code": 0,
    "msg": "success"
}
```
```

--------------------------------

### GET /api/v1/application/list

Source: https://localapi-doc-zh.adspower.net/docs/aDX0q5

查询应用分类列表。此接口允许您获取应用分类的信息，以便进行后续的环境创建或编辑操作。支持分页查询。

```APIDOC
## GET /api/v1/application/list

### Description
查询应用分类列表。此接口允许您获取应用分类的信息，以便进行后续的环境创建或编辑操作。支持分页查询。

### Method
GET

### Endpoint
/api/v1/application/list

### Parameters
#### Query Parameters
- **page** (text) - Optional - 页码默认1第一页。
- **page_size** (text) - Optional - 每页条数默认1条。

### Request Example
```
GET /api/v1/application/list?page=1&page_size=10
```

### Response
#### Success Response (200)
- **data.list** (array) - 应用分类列表，包含id, name, remark。
- **data.page** (integer) - 当前页码。
- **data.page_size** (integer) - 每页条数。
- **code** (integer) - 0 表示成功。
- **msg** (string) - Success 表示成功信息。

#### Error Response (non-200)
- **code** (integer) - -1 表示失败。
- **data** (object) - 空对象。
- **msg** (string) - 失败信息。

#### Response Example
```json
{
    "data": {
        "list": [
            {
                "id": "XXX", 
                "name": "XXX",
                "remark": "XXX"
            }
        ],
        "page": 1,
        "page_size": 10
    },
    "code": 0,
    "msg": "Success"
}
```
```

--------------------------------

### Response Example: Query Local Active Browsers (JSON)

Source: https://localapi-doc-zh.adspower.net/docs/SWZF3h

Example JSON response for a successful query of local active browsers. It returns a list of active browser objects, each containing connection details and identifiers.

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "list": [
            {
                "user_id": "xxx",
                "ws": {
                    "puppeteer": "ws://127.0.0.1:xxxx/devtools/browser/xxxxxx",
                    "selenium": "127.0.0.1:xxxx"
                },
                "debug_port": "xxxx",
                "webdriver": "xxxx"
            }
        ]
    }
}
```

--------------------------------

### Start Browser and Navigate using Playwright (JavaScript)

Source: https://localapi-doc-zh.adspower.net/docs/uYdU0j

This snippet uses the Playwright library in JavaScript to connect to a browser instance managed by AdsPower via the Chrome DevTools Protocol (CDP). It first makes an HTTP request to the AdsPower local API to get the browser's WebSocket endpoint, then connects Playwright to it, opens a new page, and navigates to a specified URL. It requires the 'axios' and 'playwright' npm packages.

```javascript
const axios = require('axios');
const { chromium } = require('playwright');


const apiKey = 'your_api_key_here'; // 定义 API Key 作为 token

axios.get('http://local.adspower.net:50325/api/v1/browser/start?user_id=xxx', {
    headers: {
        'Authorization': `Bearer ${apiKey}`
    }
}).then(async (res) => {
    console.log(res.data);
    if (res.data.code === 0 && res.data.data.ws && res.data.data.ws.puppeteer) {
        try {
            const browser = await chromium.connectOverCDP(res.data.data.ws.puppeteer);
            const defaultContext = browser.contexts()[0];
            // const page = defaultContext.pages()[0];
            const page = await defaultContext.newPage();
            await page.goto('https://www.browserscan.net');
            // await browser.close();
        } catch (err) {
            console.log(err.message);
        }
    }
}).catch((err) => {
    console.log(err)
});

```

--------------------------------

### Start and Control Browser with Selenium (Java)

Source: https://localapi-doc-zh.adspower.net/docs/uYdU0j

This Java code snippet demonstrates how to automate a browser using Selenium with the AdsPower Local API. It starts a browser instance by making an HTTP request to the AdsPower API, retrieves the necessary debugger address and webdriver path, and then initializes a ChromeDriver. The snippet also includes functionality to navigate to a URL, capture the browser title, and gracefully close the browser instance and its associated API connection. It requires Selenium WebDriver, Google Gson, and Java's built-in HTTP client.

```java
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;


public class AdsDemo {
    WebDriver driver;

    private String apiKey = "your_api_key_here"; // 定义 API Key 作为 token
    private String adsId = "xxxx";

    private WebDriver getDriver() {
        try {
            // 构建启动浏览器的 URL
            String openUrl = "http://local.adspower.net:50325/api/v1/browser/start?user_id=" + adsId;

            // 发送 HTTP GET 请求，带 Authorization Bearer Token
            JsonObject result = makeHttpRequest(openUrl);

            // 检查响应状态
            if (result.get("code").getAsInt() != 0) {
                System.out.println("Error: " + result.get("msg").getAsString());
                System.out.println("Please check ads_id");
                return null;
            }

            // 获取返回的数据
            JsonObject data = result.getAsJsonObject("data");
            String chromeDriver = data.get("webdriver").getAsString();
            String debuggerAddress = data.getAsJsonObject("ws").get("selenium").getAsString();

            // 设置 webdriver 路径
            System.setProperty("webdriver.chrome.driver", chromeDriver);

            // 配置 Chrome 选项
            ChromeOptions options = new ChromeOptions();
            options.setExperimentalOption("debuggerAddress", debuggerAddress);

            // 创建 WebDriver 实例
            driver = new ChromeDriver(options);
            driver.get("https://www.browserscan.net/");

            return driver;
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }


    private JsonObject makeHttpRequest(String url) throws Exception {
        // 创建 HTTP 客户端
        HttpClient client = HttpClient.newHttpClient();

        // 构建请求，添加 Authorization Bearer Token header
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "Bearer " + apiKey)
                .GET()
                .build();
        // 发送请求并获取响应
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        // 解析 JSON 响应
        return JsonParser.parseString(response.body()).getAsJsonObject();
    }

    public void closeBrowser() {
        try {
            if (driver != null) {
                driver.quit();
            }
            // 关闭浏览器的 API 请求
            String closeUrl = "http://local.adspower.net:50325/api/v1/browser/stop?user_id=" + adsId;
            makeHttpRequest(closeUrl);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static void main(String[] args) {
        AdsDemo demo = new AdsDemo();
        WebDriver driver = demo.getDriver();

        if (driver != null) {
            System.out.println("Browser started successfully!");
            System.out.println("Title: " + driver.getTitle());

            // 等待用户输入后关闭
            System.out.println("Press Enter to close browser...");
            try {
                System.in.read();
            } catch (Exception e) {
                e.printStackTrace();
            }
            demo.closeBrowser();
        }
    }
}
           

```

--------------------------------

### Create Group Request and Response Examples

Source: https://localapi-doc-zh.adspower.net/docs/uyznMF

Examples of request and response bodies for the 'Create Group' API. The request body specifies the group name and an optional remark. The response indicates success or failure, returning a group ID upon success.

```JSON
{
  "group_name": "group1",
  "remark": "123"
}
```

```JSON
//执行成功
{
  "code": 0,
  "data": {
    "group_id":"xxxxxxx",
    "group_name":"group1",
    "remark": "xxxxxx"
  },
  "msg": "Success"
}

//执行失败
{
  "code":-1,
  "data":{},
  "msg":"failed"
}
```

--------------------------------

### 启动浏览器 API (GET /api/v1/browser/start)

Source: https://localapi-doc-zh.adspower.net/docs/Exqfpw

此 API 用于启动浏览器实例。它需要一个环境 ID (`user_id`) 或序列号 (`serial_number`) 来启动。成功启动后，它会返回用于 Selenium 和 Puppeteer 自动化的 WebSocket/Debug 接口，以及 WebDriver 的本地路径。支持通过 `launch_args` 参数传递自定义启动参数，并可配置是否启用 Headless 模式、禁用密码填充、清除缓存等。

```HTTP
GET /api/v1/browser/start
```

--------------------------------

### GET /api/v1/user/list

Source: https://localapi-doc-zh.adspower.net/docs/aUDCic

Retrieves a list of created environment information, including proxy details, proxy IDs, and other relevant attributes. Supports filtering by group, user, and serial number, as well as sorting and pagination.

```APIDOC
## GET /api/v1/user/list

### Description
Queries for created environment information, including proxy details and proxy IDs.

### Method
GET

### Endpoint
/api/v1/user/list

### Parameters
#### Query Parameters
- **group_id** (string) - Optional - Specifies a group ID to query environments within that group. If not provided, environments from all groups are queried.
- **user_id** (string) - Optional - Specifies a user ID to query environments associated with that user.
- **serial_number** (string) - Optional - Specifies a serial number to query a specific environment.
- **user_sort** (object) - Optional - Specifies the sorting order for the query results. Supported fields are `serial_number`, `last_open_time`, and `created_time`. Values can be `"asc"` (ascending) or `"desc"` (descending). Example: `{"serial_number":"desc"}`.
- **page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **page_size** (integer) - Optional - The number of items per page. Defaults to 1, with a maximum of 100.

### Request Example
```json
{
  "group_id": "1001",
  "user_id": "xxxxxxx",
  "serial_number": "123",
  "user_sort": {"serial_number": "desc"},
  "page": 1,
  "page_size": 50
}
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **data** (object) - Contains the list of environments and pagination details.
  - **list** (array) - An array of environment objects.
    - **serial_number** (string) - Environment serial number.
    - **user_id** (string) - User ID.
    - **name** (string) - Environment name.
    - **group_id** (string) - Group ID.
    - **group_name** (string) - Group name.
    - **domain_name** (string) - Associated domain name.
    - **username** (string) - Username.
    - **remark** (string) - Remarks for the environment.
    - **sys_app_cate_id** (string) - System application category ID.
    - **created_time** (string) - Timestamp of creation.
    - **ip** (string) - IP address.
    - **ip_country** (string) - Country code of the IP address.
    - **password** (string) - Password (usually empty).
    - **last_open_time** (string) - Timestamp of the last open time.
  - **page** (integer) - Current page number.
  - **page_size** (integer) - Number of items per page.
- **msg** (string) - Success message, e.g., "Success".

#### Error Response (non-200)
- **code** (integer) - -1 for failure.
- **data** (object) - Empty object.
- **msg** (string) - Error message, e.g., "failed".

### Response Example (Success)
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "serial_number": "1",
        "user_id": "XXX",
        "name": "XXX",
        "group_id": "1",
        "group_name": "XX",
        "domain_name": "facebook.com",
        "username": "username",
        "remark": "remark",
        "sys_app_cate_id": "X",
        "created_time": "1612520997",
        "ip": "13.251.172.174",
        "ip_country": "sg",
        "password": "",
        "last_open_time": "1621333030"
      }
    ],
    "page": 1,
    "page_size": 50
  },
  "msg": "Success"
}
```

### Response Example (Failure)
```json
{
  "code": -1,
  "data": {},
  "msg": "failed"
}
```
```

--------------------------------

### Create Proxy API Request Body Example

Source: https://localapi-doc-zh.adspower.net/docs/chuang-jian-dai-li

This JSON object represents the request body for creating a proxy. It includes required parameters like 'type', 'host', and 'port', along with optional parameters such as 'user', 'password', 'proxy_url', 'remark', and 'ipchecker'.

```json
{
  "type": "http",
  "host": "192.168.0.1",
  "port": "8000",
  "user": "user12345678",
  "password": "password",
  "proxy_url": "ttps://www.baidu.com/",
  "remark": "备注内容",
  "ipchecker": "ip2location"
}
```

--------------------------------

### Query Proxies API Response Data

Source: https://localapi-doc-zh.adspower.net/docs/cha-xun-dai-li

Illustrates the structure of the response data for the query proxies API. It includes examples for both successful responses (with proxy details, total count, and pagination) and failed responses (with error code and message).

```JSON
// Successful execution
{
    "data": {
        "list": [
            {
                "proxy_id": "xxx", 
                "type": "http",
                "host": "192.168.0.1",
                "port": "8000",
                "user": "",
                "password": "",
                "proxy_url": "",
                "remark": "remark",
                "ipchecker": "ip2location",
                "proxy_partner": "",
                "profile_count": "0",
                "related_profile_no": [],
                "proxy_tags": []
            },
            {
                "proxy_id": "xxx",
                "type": "https",
                "host": "192.168.0.1",
                "port": "8001",
                "user": "username",
                "password": "password",
                "proxy_url": "https://www.baidu.com/",
                "remark": "remark1",
                "ipchecker": "ipfoxy",  
                "proxy_partner": "",
                "profile_count": "2",
                "related_profile_no": ["xxx","xxx"],
                "proxy_tags": [
                   {
                        "name": "proxytagsname",
                        "color": "blue",
                        "id": "34117"
                    }
                ]
            }
        ],
        "total": 2,
        "page": 1,
        "page_size": 10
    },
    "code": 0,
    "msg": "Success"
}

// Failed execution
{
  "code":-1,
  "data":{},
  "msg":"failed"
}
```

--------------------------------

### API Response Examples for Browser Status Check

Source: https://localapi-doc-zh.adspower.net/docs/jian-cha-qi-dong-zhuang-tai-kua-she-bei

Illustrates the JSON response formats for the browser status check API. Includes successful responses for open environments with user details, successful responses for closed environments, and general failure responses with error codes and messages.

```json
// Environment is open
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "user_id": "xxx",
            "account": "user_xxx"
        }
    ]
}

// Environment is not open
{
    "code": 0,
    "msg": "success",
    "data": []
}

// Request failed
{
  "code":-1,
  "data":{},
  "msg":"failed"
}
```

--------------------------------

### POST /api/v1/browser/cloud-active

Source: https://localapi-doc-zh.adspower.net/docs/jian-cha-qi-dong-zhuang-tai-kua-she-bei

Checks the startup status of specified browser environments. It requires a list of environment IDs and supports cross-device queries. Note: If 'Multi-open mode' is enabled, the detailed status will not be available.

```APIDOC
## POST /api/v1/browser/cloud-active

### Description
Used to check the startup status of a specified browser environment, requiring an environment ID and supporting cross-device queries. Up to 100 environments can be queried at once. If the team enables 'Multi-open mode', specific status cannot be queried, and the returned content will be the same as 'environment not opened'.

### Method
POST

### Endpoint
/api/v1/browser/cloud-active

### Parameters
#### Request Body
- **user_ids** (text) - Required - Environment IDs, unique IDs generated after successful environment creation.

### Request Example
```json
{
  "user_ids": "h1yynkm,h2yynks"
}
```

### Response
#### Success Response (200)
- **code** (integer) - Response code. 0 for success, -1 for failure.
- **msg** (string) - Response message.
- **data** (array) - An array of objects, where each object contains:
  - **user_id** (string) - Environment ID.
  - **account** (string) - The user account that opened the environment.

#### Response Example
```json
// Environment is open
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "user_id": "xxx",
            "account": "user_xxx"
        }
    ]
}

// Environment is not open
{
    "code": 0,
    "msg": "success",
    "data": []
}

// Execution failed
{
  "code": -1,
  "data": {},
  "msg": "failed"
}
```
```
Tokens:
Raw