Browserless Proxy API

openapi: 3.2.0
info:
  title: Browserless Proxy API
  version: 2.57.0
  description: 'This is the API reference for **Browserless Enterprise and Cloud** deployments. You''ll find endpoints for capturing screenshots and PDFs, scraping content, running custom browser functions, solving CAPTCHAs, bypassing bot detection with stealth browsing, managing authenticated browser profiles, and orchestrating crawls.


    The API includes REST endpoints (JSON in, JSON or binary out), WebSocket connections for direct CDP/Playwright/Puppeteer access, and CDP extensions that expose Browserless-specific commands like `liveURL`, `solveCaptcha`, and `reconnect`. For the open-source container API, see the GitHub repository.


    ## Just Getting Started?


    Check out the Quick Start guide to launch your first session, or explore the BrowserQL IDE for a GraphQL-based automation workflow.


    ## Base URL


    All API requests go to your deployment''s base URL. For Browserless Cloud:


    ```plaintext

    https://production-sfo.browserless.io

    ```


    Self-hosted Enterprise deployments use the host and port where the container is running (default `http://localhost:3000`).


    ## Authentication


    Include your API token as a query parameter on every request:


    ```plaintext

    https://production-sfo.browserless.io/chromium/content?token=YOUR_API_TOKEN

    ```


    Tokens are managed from the Account dashboard. Self-hosted deployments set the token via the `TOKEN` environment variable. See connection details for all authentication options.


    ## Changelog


    For release notes and version history, see the Enterprise Changelog.


    ## Software keys


    Self-hosted Enterprise deployments use time-limited software keys for offline licensing. No external connections or callbacks are required. Keys are cryptographically secure and can''t be reverse engineered. When a key expires, the container exits with a semantic error code.


    To use a software key, set the `KEY` environment variable when running the container:


    ```bash

    docker run -e KEY=your-generated-key browserless/enterprise

    ```'
servers:
- url: https://production-sfo.browserless.io
security:
- tokenAuth: []
tags:
- name: Proxy
  description: 'Discover available proxy locations and configure residential or datacenter routing for your sessions.


    > Residential proxies are only available on Enterprise and Cloud plans.


    Add these parameters to your library or API calls:


    - `?proxy=residential` — residential proxy (6 units/MB).

    - `?proxy=datacenter` — datacenter proxy pool (2 units/MB). Cheaper but more easily detected.

    - `?proxyCountry=us` — two-digit ISO country code.

    - `?proxySticky=true` — keep the same IP for the entire session. Recommended for most cases.

    - `?proxyPreset=px_gov01` — website-specific proxy configuration.'
  x-displayName: Proxy
paths:
  /proxy/cities:
    get:
      description: 'Returns a list of available cities for proxy connections.


        This endpoint requires city proxying to be enabled on your plan.


        Query Parameters:

        - country (optional): Filter cities by two-letter country code (e.g., ''US'', ''GB'', ''DE'')


        The response includes a list of available cities grouped by country code.'
      parameters:
      - in: query
        name: blockAds
        schema:
          description: 'Whether or not to load ad-blocking extensions for the session.

            This currently uses uBlock-Lite and may cause certain sites

            to not load properly.'
          type: boolean
      - in: query
        name: blockAdsInclude
        schema:
          description: Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.
          type: string
      - in: query
        name: country
        schema:
          description: Optional two-letter country code to filter cities by country (e.g., 'US', 'GB', 'DE').
          type: string
      - in: query
        name: launch
        schema:
          description: 'Launch options, which can be either an object

            of puppeteer.launch options or playwright.launchServer

            options, depending on the API. Must be either JSON

            object, or a base64-encoded JSON object.'
          anyOf:
          - $ref: '#/components/schemas/CDPLaunchOptions'
          - $ref: '#/components/schemas/BrowserServerOptions'
          - type: string
      - in: query
        name: profile
        schema:
          description: 'Name of an authenticated profile to hydrate into the browser at launch.

            The profile''s cookies, localStorage and IndexedDB are injected via CDP

            before your code runs. No-op in builds without a profile subsystem.'
          type: string
      - in: query
        name: timeout
        schema:
          description: 'Override the system-level timeout for this request.

            Accepts a value in milliseconds.'
          type: number
      - in: query
        name: token
        schema:
          description: The authorization token
          type: string
      - in: query
        name: trackingId
        schema:
          description: Custom session identifier
          type: string
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  countries:
                    description: Countries with their available cities
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          description: Two-letter country code
                          type: string
                        cities:
                          description: List of city names in this country
                          type: array
                          items:
                            type: string
                      additionalProperties: false
                      required:
                      - cities
                      - code
                  totalCountries:
                    description: Total number of countries
                    type: number
                  totalCities:
                    description: Total number of cities across all countries
                    type: number
                  filters:
                    description: Applied filters
                    type: object
                    properties:
                      country:
                        type: string
                    additionalProperties: false
                additionalProperties: false
                required:
                - countries
                - filters
                - totalCities
                - totalCountries
                $schema: http://json-schema.org/draft-07/schema#
        '400':
          code: 400
          description: The request contains errors or didn't properly encode content.
          message: HTTP/1.1 400 Bad Request
        '401':
          code: 401
          description: The request is missing, or contains bad, authorization credentials.
          message: HTTP/1.1 401 Unauthorized
        '403':
          code: 403
          description: The request targets a destination that is not allowed.
          message: HTTP/1.1 403 Forbidden
        '404':
          code: 404
          description: Resource couldn't be found.
          message: HTTP/1.1 404 Not Found
        '408':
          code: 408
          description: The request took has taken too long to process.
          message: HTTP/1.1 408 Request Timeout
        '429':
          code: 429
          description: Too many requests are currently being processed.
          message: HTTP/1.1 429 Too Many Requests
        '500':
          code: 500
          description: An internal error occurred when handling the request.
          message: HTTP/1.1 500 Internal Server Error
        '503':
          code: 503
          description: Service is unavailable.
          message: HTTP/1.1 503 Service Unavailable
      summary: /proxy/cities
      tags:
      - Proxy
      operationId: getProxyCities
      x-operation-id-source: derived
components:
  schemas:
    Record_string_string_undefined:
      type: object
      additionalProperties: false
    CDPLaunchOptions:
      type: object
      additionalProperties: {}
      properties:
        args:
          type: array
          items:
            type: string
        defaultViewport:
          type: object
          properties:
            deviceScaleFactor:
              type: number
            hasTouch:
              type: boolean
            height:
              type: number
            isLandscape:
              type: boolean
            isMobile:
              type: boolean
            width:
              type: number
          additionalProperties: false
          required:
          - height
          - width
        devtools:
          type: boolean
        dumpio:
          type: boolean
        headless:
          enum:
          - false
          - shell
          - true
        ignoreDefaultArgs:
          anyOf:
          - type: array
            items:
              type: string
          - type: boolean
        ignoreHTTPSErrors:
          type: boolean
        acceptInsecureCerts:
          type: boolean
        slowMo:
          type: number
        stealth:
          type: boolean
        timeout:
          type: number
        userDataDir:
          type: string
        waitForInitialPage:
          type: boolean
    BrowserServerOptions:
      type: object
      additionalProperties: {}
      properties:
        args:
          type: array
          items:
            type: string
        chromiumSandbox:
          type: boolean
        devtools:
          type: boolean
        downloadsPath:
          type: string
        env:
          description: 'Environment for the browser process. Honored by both puppeteer.launch and

            playwright.launchServer. Set server-side to give the session its own TMPDIR

            (see generateScratchDir); a caller-supplied value is merged under it, since

            a session must not be able to point its scratch back at the shared temp dir.


            That merge happens on the object handed to `launch` only. It is kept off

            the session''s stored `launchOptions`, which /sessions serves verbatim.'
          $ref: '#/components/schemas/Record_string_string_undefined'
        headless:
          type: boolean
        ignoreDefaultArgs:
          anyOf:
          - type: array
            items:
              type: string
          - type: boolean
        proxy:
          type: object
          properties:
            bypass:
              type: string
            password:
              type: string
            server:
              type: string
            username:
              type: string
          additionalProperties: false
          required:
          - server
        timeout:
          type: number
        tracesDir:
          type: string
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: query
      name: token
      description: Your Browserless API token. Find it on your [Account dashboard](https://www.browserless.io/account).
x-tagGroups:
- name: Core APIs
  tags:
  - Screenshots & PDFs
  - Scraping & Content
  - Functions & Downloads
- name: Browser Control
  tags:
  - Sessions & Connections
  - Browser Management
  - Crawling
- name: Anti-Bot & Stealth
  tags:
  - Unblock & Stealth
  - Proxy
- name: Auth & Profiles
  tags:
  - Profiles
  - Integrations
- name: WebSocket / CDP
  tags:
  - WebSocket APIs
  - Agent
  - BQL Execution
  - CDP & DevTools Connections
- name: Chrome
  tags:
  - Chrome (licensed build)
- name: Platform
  tags:
  - Platform / Skills