Browserless API Guide: REST Endpoints, CDP WebSockets, and When to Use It

What Browserless API Actually Is

Browserless has three layers that people often blur together: its managed Browsers as a Service offering, its REST API, and its newer BrowserQL surface. For the `browserless api` query, the real answer is simpler: Browserless exposes remote browsers through WebSockets and exposes browser jobs through HTTP.

The official quick start recommends CDP WebSockets for both Playwright and Puppeteer. The API reference then layers on task endpoints for screenshots, PDFs, content extraction, scraping, sessions, and browser management.

REST vs WebSocket

This is the key architecture choice. Browserless supports both because they solve different operational problems.

If your product needs a browser as a function, REST is attractive. If your product needs a browser as a long-lived remote runtime, WebSockets are the better fit.

Quick Start

Browserless publishes a cloud WebSocket endpoint pattern on its quick-start page. The cloud path is operationally the fastest because you do not have to manage Chrome versions, patches, or worker pools.

import puppeteer from 'puppeteer-core';

const TOKEN = 'YOUR_API_TOKEN';

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io?token=${TOKEN}`,
});

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

curl -X POST https://production-sfo.browserless.io/chrome/screenshot?token=YOUR_API_TOKEN \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "options": {
      "fullPage": true
    }
  }'

The exact route and payload vary by endpoint family, but that shape is the point: REST mode hides browser orchestration; WebSocket mode exposes it.

Endpoint Families

The current Browserless API reference is broad enough that you should think in endpoint families rather than individual routes.

Browserless vs Plain Playwright

The question is not whether Browserless replaces Playwright. It does not. The question is whether you want to run Playwright against your own browser fleet or against Browserless infrastructure.

If you want a higher-level, agent-driven browser stack, compare Browserless with tools like Browser Use. If you just want to stop managing headless Chrome fleets, Browserless is the more direct answer.

Cloud vs Self-Hosted

Browserless supports both hosted and Docker-based deployment. Hosted is the fastest path to value. Self-hosted is the answer when compliance, traffic shape, or data locality force the browser runtime back into your environment.

FAQ