Automation API Reference

NestBrowser exposes a local REST API that allows you to programmatically control browser profiles. This API is compatible with ChromeDriver, meaning it works with Selenium, Puppeteer, Playwright, and virtually any automation framework.

🔒 The API is only available on Professional and Enterprise plans.

How It Works

1. NestBrowser runs a local HTTP server (default: http://localhost:19222)
2. You call the API to start a profile — NestBrowser launches a browser and returns a WebSocket debugger URL
3. Your automation code connects to that URL using standard WebDriver protocols
4. The browser runs with the full NestBrowser fingerprint applied

Starting the API Server

1. Open NestBrowser → Settings → API
2. Toggle Enable API to on
3. Note the API port (default: 19222)

Basic API Usage

Start a Profile

POST http://localhost:19222/api/v1/browser/start
Content-Type: application/json

{
  "profile_id": "your-profile-id"
}

Response:

{
  "code": 0,
  "data": {
    "ws": {
      "puppeteer": "ws://localhost:9222/devtools/browser/abc123",
      "selenium": "ws://localhost:9222/devtools/browser/abc123"
    },
    "http": "http://localhost:9222",
    "webdriver": "http://localhost:9222"
  }
}

Stop a Profile

POST http://localhost:19222/api/v1/browser/stop
Content-Type: application/json

{
  "profile_id": "your-profile-id"
}

List All Profiles

GET http://localhost:19222/api/v1/profiles

Using with Puppeteer

const puppeteer = require('puppeteer-core');

async function main() {
  // 1. Start the profile via NestBrowser API
  const response = await fetch('http://localhost:19222/api/v1/browser/start', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ profile_id: 'your-profile-id' })
  });
  const { data } = await response.json();

  // 2. Connect Puppeteer to the running browser
  const browser = await puppeteer.connect({
    browserWSEndpoint: data.ws.puppeteer,
    defaultViewport: null
  });

  // 3. Control the browser
  const page = await browser.newPage();
  await page.goto('https://example.com');
  console.log(await page.title());

  // 4. Stop the profile when done
  await browser.disconnect();
  await fetch('http://localhost:19222/api/v1/browser/stop', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ profile_id: 'your-profile-id' })
  });
}

main();

Using with Playwright

import asyncio
from playwright.async_api import async_playwright
import httpx

async def main():
    # 1. Start profile
    async with httpx.AsyncClient() as client:
        r = await client.post('http://localhost:19222/api/v1/browser/start',
            json={'profile_id': 'your-profile-id'})
        ws_url = r.json()['data']['ws']['puppeteer']

    # 2. Connect Playwright
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(ws_url)
        page = browser.contexts[0].pages[0]
        await page.goto('https://example.com')
        print(await page.title())

asyncio.run(main())

Using with Selenium

from selenium import webdriver
from selenium.webdriver.chrome.options import Options
import requests

# 1. Start profile
response = requests.post('http://localhost:19222/api/v1/browser/start',
    json={'profile_id': 'your-profile-id'})
debugger_url = response.json()['data']['http']

# 2. Connect Selenium via Chrome DevTools Protocol
options = Options()
options.add_experimental_option('debuggerAddress', debugger_url.replace('http://', ''))

driver = webdriver.Chrome(options=options)
driver.get('https://example.com')
print(driver.title)

API Reference

Authentication

The local API does not require authentication by default (it’s only accessible from localhost). For production use, you can enable an API key in Settings → API → Enable API Key.

GET http://localhost:19222/api/v1/profiles
X-NestBrowser-Token: your-api-key

Profile Endpoints

Endpoint	Method	Description
/api/v1/profiles	GET	List all profiles
/api/v1/browser/start	POST	Start a profile
/api/v1/browser/stop	POST	Stop a profile
/api/v1/browser/active	GET	List running profiles

Profile Start Options

{
  "profile_id": "string",        // required
  "headless": false,             // run without UI (default: false)
  "args": ["--mute-audio"],      // extra Chrome arguments
  "load_extensions": true        // load profile extensions
}

Rate Limits

• Maximum 10 simultaneous profiles on Professional plan
• Maximum 50 simultaneous profiles on Enterprise plan
• API requests: 100 per minute

Troubleshooting

API returns “connection refused”: Make sure you’ve enabled the API in NestBrowser Settings and the local server is running.

Browser disconnects during automation: The browser is still running — your WebSocket connection timed out. Reconnect using the same profile start endpoint.

Fingerprint not applying to automated browser: Ensure you’re connecting via the WebSocket URL returned by the API (not launching Chrome directly). The fingerprint injection happens at the NestBrowser level.