REST APIs

Browserless REST APIs provide HTTP endpoints for common browser tasks like screenshots, PDFs, content scraping, file downloads, function execution, and website unblocking. Perform browser automation via simple HTTP requests without managing browser infrastructure.

Quick Start

Scrape a website with a single HTTP request:

1. Sign Up

   Sign up for a Browserless account (free plan available).

2. Get API Token

   Get your API token from the account dashboard.

3. Run Your First Request

   cURL

   curl -X POST "https://production-sfo.browserless.io/scrape?token=YOUR_API_TOKEN_HERE" \
        -H "Content-Type: application/json" \
        -d '{"url":"https://example.com","elements":[{"selector":"h1"}]}'

   Node.js

   const response = await fetch(
     'https://production-sfo.browserless.io/scrape?token=YOUR_API_TOKEN_HERE',
     {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
         url: 'https://example.com',
         elements: [{ selector: 'h1' }]
       })
     }
   );
   const data = await response.json();
   console.log(data);

   Python

   import requests
   
   response = requests.post(
       'https://production-sfo.browserless.io/scrape?token=YOUR_API_TOKEN_HERE',
       json={
           'url': 'https://example.com',
           'elements': [{'selector': 'h1'}]
       }
   )
   data = response.json()
   print(data)

   Expected response:

   {
     "data": [
       {
         "title": "Example Domain",
         "description": "Example Domain. This domain is for use in illustrative examples..."
       }
     ]
   }

Which API Should I Use?

API	Best For	Input	Output
/content	Getting fully rendered HTML, including JS-rendered content	URL or raw HTML	text/html
/scrape	Extracting structured data with CSS selectors	URL + elements array of CSS selectors	application/json
/screenshot	Capturing full-page or viewport screenshots	URL or raw HTML + Puppeteer options	image/png, image/jpeg, or image/webp
/pdf	Generating PDF documents from pages	URL or raw HTML + Puppeteer options	application/pdf
/function	Running custom Puppeteer code server-side	JavaScript code (+ optional context object)	Any (based on function return type)
/download	Retrieving files that Chrome downloads during execution	JavaScript code (+ optional context object)	Any (matches downloaded file)
/export	Fetching a URL and streaming it in its native content type	URL	Any (native content type, or zip with includeResources)
/unblock	Bypassing CAPTCHAs and bot detection	URL + data flags (content, cookies, screenshot, browserWSEndpoint)	application/json (HTML, cookies, screenshot, WebSocket endpoint)
/performance	Running Lighthouse audits for SEO, accessibility, and speed	URL + optional Lighthouse config	application/json (Lighthouse metrics)

REST API Limitations

REST APIs are stateless, single-action endpoints. Each request launches a browser, performs one task, and closes the session. Keep these constraints in mind:

• No multi-step workflows — you cannot click a button, fill a form, and then scrape the result in a single request. Each call is independent (except through /function, which still runs in a single session).
• No session persistence — cookies and state are discarded after every response. Use BaaS sessions or BrowserQL persisted state if you need to keep a browser alive between requests.
• Limited bot-detection bypass — /unblock handles basic protections, but sites with advanced fingerprinting or interactive CAPTCHAs may still block requests. Use BrowserQL for advanced stealth and CAPTCHA solving.
• No real-time interaction — you cannot observe the page, react to changes, or branch logic mid-execution (except through /function, through the Live Debugger). To prototype and debug Puppeteer code with a live browser view, use the Live Debugger in your account dashboard, then deploy the working code via the /function API.

Authentication

All REST API requests require an API token. Include your token as a query parameter:

https://production-sfo.browserless.io/scrape?token=YOUR_API_TOKEN_HERE

Get your API token from the Browserless dashboard.

Bot Detection

For sites with sophisticated bot detection, use BrowserQL which provides advanced stealth capabilities and CAPTCHA solving.

Next Steps

Launch Parameters

Configure stealth mode, proxies, and browser options

Request Configuration

Configure navigation, resource blocking, and error handling

Timeout Configuration

Control request timeouts and navigation waits