REST APIs

Browserless REST APIs provide HTTP endpoints for common browser tasks like screenshots, PDFs, content scraping, file downloads, function execution, and website unblocking. Use them when you want a single HTTP request to do one browser task 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)

   Response

   {
     "data": [
       {
         "results": [
           {
             "html": "Example Domain",
             "text": "Example Domain"
           }
         ],
         "selector": "h1"
       }
     ]
   }

Which API Should I Use?

API	Best For	Input	Output
/smart-scrape	Scraping a page with automatic fallbacks for blocked or JavaScript-heavy sites	URL + optional output formats	application/json
/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
/search	Searching the web and optionally scraping result pages	Query + optional sources and scrape options	application/json
/map	Discovering URLs on a site or sitemap	Base URL + optional search and sitemap settings	application/json
/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)
/crawl	Asynchronously crawling an entire site and scraping every page	URL + depth, path filters, scrape options	application/json (structured page data)

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. To prototype and debug Puppeteer code with a live browser view, use the Live Debugger in your Browserless dashboard, then deploy the working code via the /function API. The REST API Playground is for building and testing REST requests, not for debugging /function code live.

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

Frequently Asked Questions

What can I do with Browserless REST APIs?

Browserless REST APIs let you take screenshots, generate PDFs, extract rendered HTML, scrape structured data, download files, run Lighthouse audits, and unblock protected sites. Each is a simple HTTP POST request.

Do I need Puppeteer or Playwright to use the REST APIs?

No. REST APIs are standalone HTTP endpoints. Send a POST request with your parameters and receive the result directly. No browser libraries, WebSocket connections, or SDKs required.

Which REST API should I use for web scraping?

Use the /content endpoint for full rendered HTML, /scrape for structured JSON extraction via CSS selectors, or /smart-scrape for an intelligent cascading approach that tries HTTP first and falls back to a full browser.

Can REST APIs handle bot-protected sites?

Yes. Use the /unblock endpoint or add stealth and proxy parameters to any REST API call. Browserless applies fingerprint randomization and CAPTCHA solving server-side.