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.
For a working example, see the Quickstart.
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 |
| 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 —
/unblockhandles 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 BaaS Debugger in your Browserless dashboard, then deploy the working code via the
/functionAPI. The REST API Playground is for building and testing REST requests, not for debugging/functioncode 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.
For sites with sophisticated bot detection, use BrowserQL which provides advanced stealth capabilities and CAPTCHA solving.
FAQ & Troubleshooting
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.