Skip to main content

REST APIs

Browserless is a cloud-based service for running headless browsers at scale. It provides multiple offerings for different use cases, all using the same cloud infrastructure but accessed in various ways.

Browserless RESTful APIs are a set of ready-made HTTP endpoints for common browser tasks (such as generating PDFs or screenshots, scraping content, etc.). These endpoints let you perform automation via simple HTTP(S) requests without writing a full script. They are great for quick integrations or one-off tasks, although not as flexible for complex flows.

Benefits of REST APIs​

  • Simplicity: Interact with browser functionality using simple HTTP requests
  • Language Agnostic: Use any programming language or tool that can make HTTP requests
  • Stateless Operations: No need to maintain browser sessions for simple operations
  • Scalability: Easily integrate browser functionality into your applications at scale
  • Low Overhead: Minimize resource usage for simple browser tasks

When to Use REST APIs​

REST APIs are ideal for:

  • Simple, one-off browser operations (screenshots, PDF generation, content extraction)
  • Integrations where maintaining a browser session is unnecessary
  • Applications written in languages without robust browser automation libraries
  • Serverless functions or microservices where simplicity is paramount
  • High-throughput scenarios where connection overhead should be minimized

For more complex automation scenarios, especially those involving bot detection bypass, consider using BrowserQL, which provides a more powerful and flexible approach.

Response codes from sites​

When you make a REST API call to Browserless, you may receive an HTTP 200 status code indicating that the connection between Browserless and your client was successful. However, the underlying site that Browserless visits may return a different status response code.

Browserless propagates the actual site's response code through response headers. If a site returns something like "Error 403 - Forbidden", you'll find that 403 status code in the response headers under X-Response-Code.

Response headers provided:

  • X-Response-Code: The HTTP status code from the target site
  • X-Response-Status: The status text from the target site
  • X-Response-URL: The final URL after any redirects
  • X-Response-IP: The IP address of the target site
  • X-Response-Port: The port used to connect to the target site

This means a successful Browserless API call (HTTP 200) can still indicate that the target site returned an error (e.g., 403, 404, 500) - check the X-Response-Code header to determine the actual site response.

Getting Started​

To use the APIs, you need a unique token, created when you sign-up for a Browserless account:

  1. Sign up for a Browserless account (free plan available).
  2. Get your API Key.

Once ready you should use this token anytime you interact with the service.

You can use this token with most of our integrations by simply appending a ?token=YOUR_API_TOKEN_HERE as a query-string parameter.

Bot Detection

For strict bot detectors where browsers and a proxy aren't enough to get past, we would recommend using BrowserQL.

Next Steps​

Before exploring all Browserless REST APIs have to offer, learn more about connecting and building an URL for your needs, and all launch parameters available:

Connection URLs

Learn about regional endpoints, authentication, and how to build URLs for your REST API requests

Launch Parameters

Configure browser behavior with stealth mode, proxy settings, ad blocking, and other launch options

Timeout Configuration

Control request timeouts, navigation waits, and element detection for reliable automation