Customize with HTTP API

CloudBrowser allows users to programmatically open browser instances via an HTTP API. This service is designed to offer browsers with stealth mode options, support for custom proxies, and the ability to keep browsing sessions open based on the client’s needs.

Please note that to send calls to this api production.cloudbrowser.ai/api/v1/Browser/ it is necessary to use your api token in each call.

Available Endpoints

1. /Open – Open a browser with advanced configurations

Method: POST

Description: This endpoint allows you to open a browser with advanced configurations, including custom browser arguments, custom proxy settings, and more.

Parameters:

• Args (optional): string[] – A list of custom browser arguments. If null, default arguments will be used.

• IgnoredDefaultArgs (optional): string[] – A list of default arguments to ignore. If null, default ignored arguments will be used.

• Headless (optional): bool – Indicates whether the browser should open in headless mode (true) or with a graphical interface (false). Default is false.

• Stealth (optional): bool – Enables or disables stealth mode. Default is true.

• Browser (optional): SupportedBrowser – Specifies the browser to use. Available options are:

  • 0 – Chrome

  • 2 – Chromium

  • 3 – ChromeHeadlessShell If not specified, Chromium is used by default.

• KeepOpen (optional): number – Specifies the minutes of inactivity before the browser automatically closes. The default is 30 seconds.

• Proxy (optional): BrowserOptionsProxy – Custom proxy configuration. If not specified, the service will use an automatically assigned proxy.

• Label (optional): string – Specifies the instance name, useful for recognizing it in the list of open remote desktops.

Request Example:

curl -X POST https://production.cloudbrowser.ai/api/v1/Browser/Open \
-H "Authorization: Bearer <your-api-token>" \
-d '{
  "Args": ["--no-sandbox", "--disable-gpu"],
  "IgnoredDefaultArgs": ["--enable-automation"],
  "Headless": true,
  "Stealth": true,
  "Browser": 2,
  "KeepOpen": true,
  "Proxy": {
      "Host": "my-proxy.com",
      "Port": "8080",
      "Username": "user",
      "Password": "password"
  },
  "Label": "app-worker01"
}'

Response:

{
  "address": "browserprovider-worker-*.cloudbrowser.ai/devtools/browser/*",
  "status": 200
}

HTTP response:

• 200 – Success: The browser was successfully opened.

• 401 – AuthorizationError: Incorrect token.

• 402 – NoSubscription: No active subscription.

• 403 – NoUnits: All units have been consumed. This can be avoided by enabling additional units in the web settings.

• 404 – BrowserLimit: Your subscription does not allow opening more browsers in parallel.

• 0 – Unknown: Unexpected error.

2. /Close – Close a browser

Description: Allows to close a browser remotely without using Puppeteer.

Method: POST

Parameters:

• address: string – The address of the browser you want to close.

Request Example:

curl -X POST https://production.cloudbrowser.ai/api/v1/Browser/Close \
-H "Authorization: Bearer <your-api-token>" \
-d '{
  "address": "browserprovider-worker-4.cloudbrowser.ai/devtools/browser/0b6d292-a6c7-4c06-83b3"
}'

3. /Get – Get all active browsers

Description: Returns a list of all currently open browsers.

Method: GET

Parameters: No parameters required.

Response:

• sessions: Array of active sessions with the following fields:

  • startedOn: Date and time when the session was started.

  • label: Session label.

  • address: Browser address.

  • vncpass: Password of the remote desktop associated to the session.

4. /StartRemoteDesktop – Start remote desktop

Description: Start a remote desktop in the selected browser.

Method: POST

Parameters:

• address: string – The address of the browser.

Request Example:

curl -X POST https://production.cloudbrowser.ai/api/v1/Browser/StartRemoteDesktop \
-H "Authorization: Bearer <your-api-token>" \
-d '{
  "address": "browserprovider-worker-4.cloudbrowser.ai/devtools/browser/0b6d292-a6c7-4c06-83b3"
}'

5. /StopRemoteDesktop – Stop remote desktop

Description: Start a remote desktop in the selected browser.

Method: POST

Parameters:

• address: string – The address of the browser.

Request Example:

curl -X POST https://production.cloudbrowser.ai/api/v1/Browser/StopRemoteDesktop \
-H "Authorization: Bearer <your-api-token>" \
-d '{
  "address": "browserprovider-worker-4.cloudbrowser.ai/devtools/browser/0b6d292-a6c7-4c06-83b3"
}'