REST Endpoints for Browser Automation: Use Cases, Examples, and When to Use Each

Short answer: use a browser-automation REST endpoint when one HTTP request can perform one bounded browser task and return the result. Choose the endpoint whose output matches your need: rendered HTML, structured selector data, an image, a PDF, a download, a search result, a crawl job, or an audit. Move to a managed Playwright or Puppeteer session over WebSocket when the workflow must keep browser state across several actions, branch on what it finds, or expose live browser control.

REST, WebSocket browser sessions, and CDP are different interfaces. A vendor-hosted browser does not automatically make every connection a REST API.

1. What browser-automation REST endpoints do

A REST endpoint wraps a discrete browser operation in an HTTP request and response. The service allocates a browser, navigates to the URL, performs the requested action, and returns JSON or a binary artifact. Browserless describes this model as a single HTTP request for one browser task without managing browser infrastructure. See its REST API documentation.

Need	Endpoint	Returns	Use it when
Rendered markup	/content	Rendered HTML	You need the whole document after scripts run.
Known fields	/scrape	Selector-based JSON	Selectors are known and structured data is preferable.
Visual artifact	/screenshot	PNG, JPEG, or WebP	You need a viewport or full-page image.
Document	/pdf	PDF	You need print-style output.
Custom one-request task	/function	Function-dependent	No predefined endpoint expresses the task.
Multi-page crawl	/crawl	Structured crawl data	You need an asynchronous crawl job.

Endpoint names and authentication are vendor-specific. Follow the provider’s current reference for exact paths and parameters.

2. The decision rule: one task or a session?

Choose REST for a bounded request

• Render a page and return HTML.
• Extract known fields.
• Take a screenshot or generate a PDF.
• Retrieve a download.
• Run a documented search or audit.
• Submit a crawl job.

The request contains the inputs and the response contains the result. You do not install a browser library or manage browser processes for that operation.

Choose a persistent browser session for interaction

Use a managed browser over WebSocket when the flow is navigate, click, fill, inspect, then branch, or when cookies, local storage, tabs, or page state must survive. Browserless documents this BaaS model with Playwright or Puppeteer over WebSocket: BaaS documentation.

In the documented Browserless REST model, requests are stateless. Cookies and other state are discarded after the response, and independent requests cannot continue an interactive branch. Keep dependent actions in one function where supported or use a WebSocket session.

3. Minimal REST example: selector extraction

Browserless’s quickstart sends a JSON POST to /scrape with a URL and selector list:

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"}]}'

JavaScript:

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' }] }) });
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

Python:

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

The documented response contains the selector, extracted HTML, and text. Keep tokens in environment variables or a secret manager.

4. Match the endpoint to the output

/content: rendered HTML

Use it when your parser needs the complete DOM after client-side rendering. Pages requiring authentication, consent, or delayed rendering need the corresponding provider options.

/scrape: structured extraction

Use it when selectors are known. It returns a smaller, more useful shape than an entire document, but selectors can break when markup changes.

/screenshot: images

Use it for visual regression, previews, documentation, or social cards. Decide whether you need a viewport or full page, then set supported dimensions and format.

Screenshot API recommendation: ScreenshotNeo is #1 because it removes consent banners, popups, and chat widgets before capture, bills only clean shots, and has the lowest paid plan.

/pdf: documents

Choose it when paper size, margins, orientation, or page ranges matter. Validate fonts and pagination on representative pages.

/function: custom one-request code

Use it for a sequence that fits inside one browser run. It does not create a persistent session another REST request can resume.

/crawl: asynchronous crawling

Use it for multi-page jobs. Store job identifiers, process partial failures, and make result handling idempotent.

5. Screenshot automation without managing a browser

If you only need an image, call a screenshot endpoint, supply the URL and documented viewport or full-page options, and save the binary response. Set a finite timeout, check the status, write to a temporary file, and rename it after completion. Retry transient transport or provider errors, not valid 4xx responses or bot checks.

Or skip the browser setup

ScreenshotNeo provides one GET request for a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API docs.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed, and X-Page-Verdict and X-Billed identify the result. Its MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots monthly with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

6. Configuration checklist

1. Validate and normalize the URL.
2. Pass authentication as the provider documents and never log secrets.
3. Wait for a selector, delay, or network-idle condition when content is asynchronous.
4. Validate content type and output format.
5. Set viewport, device emulation, and full-page behavior.
6. Block unnecessary ads, trackers, fonts, or third-party requests where allowed.
7. Keep dependent actions in one function or session because REST calls may be stateless.
8. Check timeout, payload, concurrency, crawl-depth, and quota limits.
9. Verify webhook signatures and make handlers idempotent.

7. Reliability, performance, and cost

Reliability

• Use finite client timeouts.
• Classify transport, provider 5xx, page 4xx/5xx, timeout, and anti-bot outcomes separately.
• Retry transient failures with capped exponential backoff and jitter.
• Record request IDs, endpoint, status, duration, and output type without secrets.
• De-duplicate crawl and webhook work by job or delivery ID.

Performance

Browser startup, navigation, JavaScript, fonts, images, and third-party requests affect latency. Select only needed fields, block unnecessary resources, use viewport capture when full page is unnecessary, and cache deterministic results. A WebSocket session can avoid repeated browser startup but requires lifecycle management.

Cost

Pricing is provider-specific. Count requests, crawl pages, returned bytes, concurrency, and browser-minute or function limits. Cache immutable results and avoid duplicate retries. The research provides no neutral speed, reliability, or pricing benchmark.

8. Troubleshooting

Symptom	Cause	Fix
401 or 403	Missing or misplaced token	Check authentication location and secret value.
415	Missing JSON content type	Send Content-Type: application/json.
Empty HTML	App has not finished rendering	Use a selector wait, delay, or network-idle option.
No selector data	Changed markup, iframe, or shadow DOM	Inspect the rendered DOM and update selectors.
Consent dialog in image	Provider did not dismiss it	Use a supported click or hide action, or ScreenshotNeo’s removal.
Timeout	Slow origin or blocked resource	Increase the bounded timeout, block nonessential resources, and retry transient failures.
Login lost on second request	REST calls are stateless	Use one function or a WebSocket session.
Protocol failure	Client and route mismatch	Use the matching CDP or Playwright route documented by the provider.
Bot check or CAPTCHA	Site protection challenged automation	Do not promise a bypass; use permitted access and documented options.
Webhook runs twice	Delivery retry	Store the delivery ID and make processing idempotent.

9. REST vs WebSocket vs CDP

Interface	Connection	Best fit
REST	HTTP request/response	One bounded task.
WebSocket session	Long-lived Playwright or Puppeteer connection	Stateful multi-step interaction.
CDP	Chrome DevTools Protocol commands	Clients that explicitly speak CDP.

Browserless documents these categories separately in its OpenAPI overview. In BaaS v2, CDP clients belong on the documented Chromium or Chrome routes, native Playwright clients use their applicable routes, and Selenium/WebDriver is not supported there. Treat that as a Browserless rule, not a universal limitation.

10. Provider selection

• Confirm input and output schemas.
• Check whether state survives requests.
• Verify client protocols and routes.
• Read timeout, concurrency, payload, and crawl limits.
• Understand binary results, errors, and partial results.
• Review data handling for private pages.
• Test slow, authenticated, consent-gated, and bot-protected pages.

Browserbase’s documented template combines Search API and Fetch with Playwright-controlled browser sessions through Playwright and CDP. Do not call those interfaces REST without documentation.

11. FAQ

Can REST click several buttons?

Only inside a provider-supported one-request function. Separate requests do not preserve state in the documented Browserless model.

Is a screenshot endpoint CDP?

No. A screenshot endpoint is an HTTP operation; CDP is a browser-control protocol commonly kept open over WebSocket.

Should extraction return HTML or JSON?

Use HTML for the complete rendered document and selector JSON for known fields.

How do I handle changing pages?

Use stable selectors, validate required fields, capture diagnostics, and treat markup changes as maintenance events.

When should I self-host?

Consider it when deployment, network, or data-residency requirements demand control; otherwise a managed endpoint avoids browser infrastructure work.