customSiteTitle: Browserless Documentation
info:
  title: Browserless
  version: 2.54.2
  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](https://docs.browserless.io/open-api#tag/CDP-Extensions) that
    expose Browserless-specific commands like `liveURL`, `solveCaptcha`, and
    `saveProfile`. For the open-source container API, see the [GitHub
    repository](https://github.com/browserless/browserless).


    ## Just Getting Started?


    Check out the [Quick Start guide](https://docs.browserless.io/baas/start) to
    launch your first session, or explore the [BrowserQL
    IDE](https://docs.browserless.io/browserql/overview) 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](https://www.browserless.io/account). Self-hosted deployments set
    the token via the `TOKEN` environment variable. See [connection
    details](https://docs.browserless.io/baas/connection) for all authentication
    options.


    ## Changelog


    For release notes and version history, see the [Enterprise
    Changelog](https://docs.browserless.io/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

    ```
openapi: 3.0.0
paths:
  /screenshot:
    post:
      description: >-
        Returns a screenshot binary from a `url` or `html` payload.

        "url" or "html" payload in your request. Many options exist including

        cookies, user-agents, setting timers and network mocks.


        **Note:** This is the preferred endpoint. The `/chromium/screenshot`
        route is equivalent.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: >-
              Restrict blockAds to a specific set of uBlock ruleset ids
              (comma-separated

              list or JSON array). Only applies when `blockAds` is true. Fewer
              rulesets

              means a faster browser launch under load; omit to load the full
              default set.
            type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            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:
          application/json:
            schema:
              properties:
                blockConsentModals:
                  description: >-
                    Whether to automatically block cookie consent modals and
                    popups.
                  type: boolean
                options:
                  $ref: '#/components/schemas/ScreenshotOptions'
                  description: >-
                    Screenshot options based on Puppeteer's ScreenshotOptions
                    interface.

                    Includes properties like `type`, `quality`, `fullPage`,
                    `clip`, etc.
                addScriptTag:
                  description: >-
                    An array of script tags to add to the page before performing
                    actions.

                    Each object can contain either a `url`, or a `content`
                    property.
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  description: >-
                    An array of style tags to add to the page before performing
                    actions.

                    Each object can contain either a `url`, or a `content`
                    property.
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  $ref: '#/components/schemas/Credentials'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless will attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  description: >-
                    An array of cookies to set on the page before navigation.

                    Each cookie object should contain at least `name` and
                    `value` properties.
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                emulateMediaType:
                  description: >-
                    Changes the CSS media type of the page. Accepts values like
                    "screen" or "print".
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  description: >-
                    HTML content to set as the page content instead of
                    navigating to a URL.
                  type: string
                rejectRequestPattern:
                  description: >-
                    An array of patterns to match against request URLs for
                    automatic rejection.

                    Requests matching these patterns will be aborted.
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  description: >-
                    An array of resource types to reject during page load.

                    Common types include "image", "stylesheet", "font",
                    "script", etc.
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  description: >-
                    An array of request interceptors that can modify or mock
                    network requests.

                    Each interceptor has a `pattern` to match URLs and a
                    `response` to return.
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            $ref: '#/components/schemas/AnyRecord'
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                setExtraHTTPHeaders:
                  description: >-
                    An object containing additional HTTP headers to send with
                    every request.
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  description: Whether or not to allow JavaScript to run on the page.
                  type: boolean
                url:
                  description: The URL to navigate to before performing actions.
                  type: string
                userAgent:
                  description: The user agent string to use for the page.
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  $ref: '#/components/schemas/Viewport'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  description: >-
                    Options for waiting for a specific event to be fired on the
                    page.
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  description: Options for waiting for a JavaScript function to execute.
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  description: >-
                    Options for waiting for a specific CSS selector to appear on
                    the page.
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  description: >-
                    The amount of time in milliseconds to wait before
                    proceeding.
                  type: number
                scrollPage:
                  description: >-
                    Whether to scroll through the entire page before capturing
                    content.

                    Useful for triggering lazy-loaded content.
                  type: boolean
                selector:
                  description: >-
                    A CSS selector to target a specific element instead of the
                    full page.
                  type: string
              type: object
              example: &ref_0
                url: https://docs.browserless.io/
            example:
              blockConsentModals: true
              options:
                optimizeForSpeed: true
                type: jpeg
                quality: 0
                fromSurface: true
                fullPage: true
                omitBackground: true
                clip:
                  scale: 0
                  width: 0
                  height: 0
                  x: 0
                  'y': 0
                encoding: base64
                captureBeyondViewport: true
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
              scrollPage: true
              selector: string
      responses:
        '200':
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                format: byte
          description: |-
            Response can either be a text/plain base64 encoded body
            or a binary stream with png/jpeg as a content-type
        '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: /screenshot
      tags:
        - Screenshots & PDFs
  /pdf:
    post:
      description: >-
        Returns a PDF binary from a `url` or `html` payload.

        "url" or "html" payload in your request. Many options exist for

        injecting cookies, request interceptors, user-agents and waiting for

        selectors, timers and more.


        **Note:** This is the preferred endpoint. The `/chromium/pdf` route is
        equivalent.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: >-
              Restrict blockAds to a specific set of uBlock ruleset ids
              (comma-separated

              list or JSON array). Only applies when `blockAds` is true. Fewer
              rulesets

              means a faster browser launch under load; omit to load the full
              default set.
            type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            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:
          application/json:
            schema:
              properties:
                blockConsentModals:
                  description: >-
                    Whether to automatically block cookie consent modals and
                    popups.
                  type: boolean
                options:
                  description: >-
                    PDF generation options based on Puppeteer's PDFOptions
                    interface.

                    Includes properties like `format`, `margin`,
                    `printBackground`, `landscape`, etc.
                  additionalProperties: false
                  type: object
                  properties:
                    scale:
                      description: >-
                        Scales the rendering of the web page. Amount must be
                        between `0.1` and `2`.
                      type: number
                    displayHeaderFooter:
                      description: Whether to show the header and footer.
                      type: boolean
                    headerTemplate:
                      description: >-
                        HTML template for the print header. Should be valid HTML
                        with the following

                        classes used to inject values into them:


                        - `date` formatted print date


                        - `title` document title


                        - `url` document location


                        - `pageNumber` current page number


                        - `totalPages` total pages in the document
                      type: string
                    footerTemplate:
                      description: >-
                        HTML template for the print footer. Has the same
                        constraints and support

                        for special classes as {@link
                        PDFOptions.headerTemplate}.
                      type: string
                    printBackground:
                      description: Set to `true` to print background graphics.
                      type: boolean
                    landscape:
                      description: Whether to print in landscape orientation.
                      type: boolean
                    pageRanges:
                      description: Paper ranges to print, e.g. `1-5, 8, 11-13`.
                      type: string
                    format:
                      $ref: '#/components/schemas/PaperFormat'
                    width:
                      description: >-
                        Sets the width of paper. You can pass in a number or a
                        string with a unit.
                      type:
                        - string
                        - number
                    height:
                      description: >-
                        Sets the height of paper. You can pass in a number or a
                        string with a unit.
                      type:
                        - string
                        - number
                    preferCSSPageSize:
                      description: >-
                        Give any CSS `@page` size declared in the page priority
                        over what is

                        declared in the `width` or `height` or `format` option.
                      type: boolean
                    margin:
                      $ref: '#/components/schemas/PDFMargin'
                      description: Set the PDF margins.
                    omitBackground:
                      description: >-
                        Hides default white background and allows generating
                        pdfs with transparency.
                      type: boolean
                    tagged:
                      description: Generate tagged (accessible) PDF.
                      type: boolean
                    outline:
                      description: Generate document outline.
                      type: boolean
                    timeout:
                      description: >-
                        Timeout in milliseconds. Pass `0` to disable timeout.


                        The default value can be changed by using {@link
                        Page.setDefaultTimeout}
                      type: number
                    waitForFonts:
                      description: >-
                        If true, waits for `document.fonts.ready` to resolve.
                        This might require

                        activating the page using {@link Page.bringToFront} if
                        the page is in the

                        background.
                      type: boolean
                    fullPage:
                      type: boolean
                addScriptTag:
                  description: >-
                    An array of script tags to add to the page before performing
                    actions.

                    Each object can contain either a `url`, or a `content`
                    property.
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  description: >-
                    An array of style tags to add to the page before performing
                    actions.

                    Each object can contain either a `url`, or a `content`
                    property.
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  $ref: '#/components/schemas/Credentials'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless will attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  description: >-
                    An array of cookies to set on the page before navigation.

                    Each cookie object should contain at least `name` and
                    `value` properties.
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                emulateMediaType:
                  description: >-
                    Changes the CSS media type of the page. Accepts values like
                    "screen" or "print".
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  description: >-
                    HTML content to set as the page content instead of
                    navigating to a URL.
                  type: string
                rejectRequestPattern:
                  description: >-
                    An array of patterns to match against request URLs for
                    automatic rejection.

                    Requests matching these patterns will be aborted.
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  description: >-
                    An array of resource types to reject during page load.

                    Common types include "image", "stylesheet", "font",
                    "script", etc.
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  description: >-
                    An array of request interceptors that can modify or mock
                    network requests.

                    Each interceptor has a `pattern` to match URLs and a
                    `response` to return.
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            $ref: '#/components/schemas/AnyRecord'
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                setExtraHTTPHeaders:
                  description: >-
                    An object containing additional HTTP headers to send with
                    every request.
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  description: Whether or not to allow JavaScript to run on the page.
                  type: boolean
                url:
                  description: The URL to navigate to before performing actions.
                  type: string
                userAgent:
                  description: The user agent string to use for the page.
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  $ref: '#/components/schemas/Viewport'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  description: >-
                    Options for waiting for a specific event to be fired on the
                    page.
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  description: Options for waiting for a JavaScript function to execute.
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  description: >-
                    Options for waiting for a specific CSS selector to appear on
                    the page.
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  description: >-
                    The amount of time in milliseconds to wait before
                    proceeding.
                  type: number
              type: object
              example: *ref_0
            example:
              blockConsentModals: true
              options:
                scale: 0
                displayHeaderFooter: true
                headerTemplate: string
                footerTemplate: string
                printBackground: true
                landscape: true
                pageRanges: string
                format: A0
                width: string
                height: string
                preferCSSPageSize: true
                margin:
                  top: string
                  bottom: string
                  left: string
                  right: string
                omitBackground: true
                tagged: true
                outline: true
                timeout: 0
                waitForFonts: true
                fullPage: true
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            application/pdf:
              schema:
                description: Responds with an application/pdf content-type and a binary PDF
                type: string
                $schema: http://json-schema.org/draft-07/schema#
          description: Responds with an application/pdf content-type and a binary PDF
        '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: /pdf
      tags:
        - Screenshots & PDFs
  /edge/screenshot:
    post:
      description: |-
        Returns a screenshot binary from a `url` or `html` payload using Edge.
        "url" or "html" payload in your request. Many options exist including
        cookies, user-agents, setting timers and network mocks.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                addScriptTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  anyOf:
                    - $ref: '#/components/schemas/Credentials'
                    - type: 'null'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                emulateMediaType:
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  type: string
                options:
                  $ref: '#/components/schemas/ScreenshotOptions'
                  description: >-
                    Screenshot options based on Puppeteer's ScreenshotOptions
                    interface.

                    Includes properties like `type`, `quality`, `fullPage`,
                    `clip`, etc.
                rejectRequestPattern:
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                            $ref: '#/components/schemas/AnyRecord'
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                scrollPage:
                  type: boolean
                selector:
                  type: string
                setExtraHTTPHeaders:
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  type: boolean
                url:
                  type: string
                userAgent:
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      description: >-
                        Used to specify User Agent Client Hints to emulate. See
                        https://wicg.github.io/ua-client-hints

                        Missing optional values will be filled in by the target
                        with what it would normally use.
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  anyOf:
                    - $ref: '#/components/schemas/Viewport'
                    - type: 'null'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  type: number
              type: object
              example: *ref_0
            example:
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              options:
                optimizeForSpeed: true
                type: jpeg
                quality: 0
                fromSurface: true
                fullPage: true
                omitBackground: true
                clip:
                  scale: 0
                  width: 0
                  height: 0
                  x: 0
                  'y': 0
                encoding: base64
                captureBeyondViewport: true
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              scrollPage: true
              selector: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                format: byte
          description: |-
            Response can either be a text/plain base64 encoded body
            or a binary stream with png/jpeg as a content-type
        '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: /edge/screenshot
      tags:
        - Screenshots & PDFs
  /edge/pdf:
    post:
      description: |-
        Returns a PDF binary from a `url` or `html` payload using Edge.
        "url" or "html" payload in your request. Many options exist for
        injecting cookies, request interceptors, user-agents and waiting for
        selectors, timers and more.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                addScriptTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  anyOf:
                    - $ref: '#/components/schemas/Credentials'
                    - type: 'null'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                emulateMediaType:
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  type: string
                options:
                  additionalProperties: false
                  type: object
                  properties:
                    scale:
                      description: >-
                        Scales the rendering of the web page. Amount must be
                        between `0.1` and `2`.
                      type: number
                    displayHeaderFooter:
                      description: Whether to show the header and footer.
                      type: boolean
                    headerTemplate:
                      description: >-
                        HTML template for the print header. Should be valid HTML
                        with the following

                        classes used to inject values into them:


                        - `date` formatted print date


                        - `title` document title


                        - `url` document location


                        - `pageNumber` current page number


                        - `totalPages` total pages in the document
                      type: string
                    footerTemplate:
                      description: >-
                        HTML template for the print footer. Has the same
                        constraints and support

                        for special classes as {@link
                        PDFOptions.headerTemplate}.
                      type: string
                    printBackground:
                      description: Set to `true` to print background graphics.
                      type: boolean
                    landscape:
                      description: Whether to print in landscape orientation.
                      type: boolean
                    pageRanges:
                      description: Paper ranges to print, e.g. `1-5, 8, 11-13`.
                      type: string
                    format:
                      description: All the valid paper format types when printing a PDF.
                      enum:
                        - A0
                        - A1
                        - A2
                        - A3
                        - A4
                        - A5
                        - A6
                        - LEDGER
                        - LEGAL
                        - LETTER
                        - Ledger
                        - Legal
                        - Letter
                        - TABLOID
                        - Tabloid
                        - a0
                        - a1
                        - a2
                        - a3
                        - a4
                        - a5
                        - a6
                        - ledger
                        - legal
                        - letter
                        - tabloid
                      type: string
                    width:
                      description: >-
                        Sets the width of paper. You can pass in a number or a
                        string with a unit.
                      type:
                        - string
                        - number
                    height:
                      description: >-
                        Sets the height of paper. You can pass in a number or a
                        string with a unit.
                      type:
                        - string
                        - number
                    preferCSSPageSize:
                      description: >-
                        Give any CSS `@page` size declared in the page priority
                        over what is

                        declared in the `width` or `height` or `format` option.
                      type: boolean
                    margin:
                      description: Set the PDF margins.
                      $ref: '#/components/schemas/PDFMargin'
                    omitBackground:
                      description: >-
                        Hides default white background and allows generating
                        pdfs with transparency.
                      type: boolean
                    tagged:
                      description: Generate tagged (accessible) PDF.
                      type: boolean
                    outline:
                      description: Generate document outline.
                      type: boolean
                    timeout:
                      description: >-
                        Timeout in milliseconds. Pass `0` to disable timeout.


                        The default value can be changed by using {@link
                        Page.setDefaultTimeout}
                      type: number
                    waitForFonts:
                      description: >-
                        If true, waits for `document.fonts.ready` to resolve.
                        This might require

                        activating the page using {@link Page.bringToFront} if
                        the page is in the

                        background.
                      type: boolean
                    fullPage:
                      type: boolean
                  description: >-
                    PDF generation options based on Puppeteer's PDFOptions
                    interface.

                    Includes properties like `format`, `landscape`, `margin`,
                    `scale`, etc.
                rejectRequestPattern:
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                            $ref: '#/components/schemas/AnyRecord'
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                setExtraHTTPHeaders:
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  type: boolean
                url:
                  type: string
                userAgent:
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      description: >-
                        Used to specify User Agent Client Hints to emulate. See
                        https://wicg.github.io/ua-client-hints

                        Missing optional values will be filled in by the target
                        with what it would normally use.
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  anyOf:
                    - $ref: '#/components/schemas/Viewport'
                    - type: 'null'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  type: number
              type: object
              example: *ref_0
            example:
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              options:
                scale: 0
                displayHeaderFooter: true
                headerTemplate: string
                footerTemplate: string
                printBackground: true
                landscape: true
                pageRanges: string
                format: A0
                width: string
                height: string
                preferCSSPageSize: true
                margin:
                  top: string
                  bottom: string
                  left: string
                  right: string
                omitBackground: true
                tagged: true
                outline: true
                timeout: 0
                waitForFonts: true
                fullPage: true
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            application/pdf:
              schema:
                description: Responds with an application/pdf content-type and a binary PDF
                type: string
                $schema: http://json-schema.org/draft-07/schema#
          description: Responds with an application/pdf content-type and a binary PDF
        '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: /edge/pdf
      tags:
        - Screenshots & PDFs
  /chromium/content:
    post:
      description: >-
        Given a `url` or `html` field, loads the page and returns the fully
        rendered HTML.


        **Note:** Also available at `/content` as a convenience alias.
      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: launch
          schema:
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                addScriptTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  anyOf:
                    - $ref: '#/components/schemas/Credentials'
                    - type: 'null'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                emulateMediaType:
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  type: string
                rejectRequestPattern:
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                            $ref: '#/components/schemas/AnyRecord'
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                setExtraHTTPHeaders:
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  description: Whether or not to allow JavaScript to run on the page.
                  type: boolean
                url:
                  type: string
                userAgent:
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      description: >-
                        Used to specify User Agent Client Hints to emulate. See
                        https://wicg.github.io/ua-client-hints

                        Missing optional values will be filled in by the target
                        with what it would normally use.
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  anyOf:
                    - $ref: '#/components/schemas/Viewport'
                    - type: 'null'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  type: number
              type: object
              example: *ref_0
            example:
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            text/html:
              schema:
                description: |-
                  An HTML payload of the website or HTML after JavaScript
                  parsing and execution.
                type: string
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            An HTML payload of the website or HTML after JavaScript
            parsing and execution.
        '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: /chromium/content
      tags:
        - Scraping & Content
  /chromium/scrape:
    post:
      description: >-
        Returns text, HTML, and metadata from a given list of CSS selectors
        against the rendered DOM.

        Debugging information is available by sending in the appropriate flags
        in the "debugOpts"

        property. Responds with an array of JSON objects.


        **Note:** Also available at `/scrape` as a convenience alias.
      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: launch
          schema:
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                addScriptTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  anyOf:
                    - $ref: '#/components/schemas/Credentials'
                    - type: 'null'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                debugOpts:
                  $ref: '#/components/schemas/ScrapeDebugOptions'
                elements:
                  type: array
                  items:
                    $ref: '#/components/schemas/ScrapeElementSelector'
                emulateMediaType:
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  type: string
                rejectRequestPattern:
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                            $ref: '#/components/schemas/AnyRecord'
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                setExtraHTTPHeaders:
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  type: boolean
                url:
                  type: string
                userAgent:
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      description: >-
                        Used to specify User Agent Client Hints to emulate. See
                        https://wicg.github.io/ua-client-hints

                        Missing optional values will be filled in by the target
                        with what it would normally use.
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  anyOf:
                    - $ref: '#/components/schemas/Viewport'
                    - type: 'null'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  type: number
              type: object
              required:
                - elements
              example: &ref_1
                url: https://docs.browserless.io/
                elements:
                  - selector: h1
            example:
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              debugOpts:
                console: true
                cookies: true
                html: true
                network: true
                screenshot: true
              elements:
                - selector: string
                  timeout: 0
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            application/json:
              schema:
                description: The JSON response body
                type: object
                properties:
                  data:
                    anyOf:
                      - type: array
                        items:
                          type: object
                          properties:
                            results:
                              type: array
                              items:
                                type: object
                                properties:
                                  attributes:
                                    description: A list of HTML attributes of the element
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        name:
                                          description: >-
                                            The name of the HTML attribute for the
                                            element
                                          type: string
                                        value:
                                          description: >-
                                            The value of the HTML attribute for the
                                            element
                                          type: string
                                      additionalProperties: false
                                      required:
                                        - name
                                        - value
                                  height:
                                    description: The height the element
                                    type: number
                                  html:
                                    description: The HTML the element
                                    type: string
                                  left:
                                    description: >-
                                      The amount of pixels from the left of the
                                      page
                                    type: number
                                  text:
                                    description: The text the element
                                    type: string
                                  top:
                                    description: >-
                                      The amount of pixels from the top of the
                                      page
                                    type: number
                                  width:
                                    description: The width the element
                                    type: number
                                additionalProperties: false
                                required:
                                  - attributes
                                  - height
                                  - html
                                  - left
                                  - text
                                  - top
                                  - width
                            selector:
                              description: The DOM selector of the element
                              type: string
                          additionalProperties: false
                          required:
                            - results
                            - selector
                      - type: 'null'
                  debug:
                    description: When debugOpts options are present, results are here
                    anyOf:
                      - type: object
                        properties:
                          console:
                            description: A list of console messages from the browser
                            type: array
                            items:
                              type: string
                          cookies:
                            description: List of cookies for the site or null
                            anyOf:
                              - type: array
                                items:
                                  $ref: '#/components/schemas/Cookie'
                              - type: 'null'
                          html:
                            description: The HTML string of the website or null
                            type:
                              - 'null'
                              - string
                          network:
                            type: object
                            properties:
                              inbound:
                                type: array
                                items:
                                  $ref: '#/components/schemas/InBoundRequest'
                              outbound:
                                type: array
                                items:
                                  $ref: '#/components/schemas/OutBoundRequest'
                            additionalProperties: false
                            required:
                              - inbound
                              - outbound
                          screenshot:
                            description: A base64-encoded string of the site or null
                            type:
                              - 'null'
                              - string
                        additionalProperties: false
                        required:
                          - console
                          - cookies
                          - html
                          - network
                          - screenshot
                      - type: 'null'
                additionalProperties: false
                required:
                  - data
                  - debug
                definitions:
                  Cookie:
                    description: Represents a cookie object.
                    type: object
                    properties:
                      path:
                        description: Cookie path.
                        type: string
                      expires:
                        description: >-
                          Cookie expiration date as the number of seconds since
                          the UNIX epoch. Set to `-1` for

                          session cookies
                        type: number
                      size:
                        description: Cookie size.
                        type: number
                      secure:
                        description: True if cookie is secure.
                        type: boolean
                      session:
                        description: True in case of session cookie.
                        type: boolean
                      partitionKeyOpaque:
                        description: >-
                          True if cookie partition key is opaque. Supported only
                          in Chrome.
                        type: boolean
                      name:
                        description: Cookie name.
                        type: string
                      value:
                        description: Cookie value.
                        type: string
                      domain:
                        description: Cookie domain.
                        type: string
                      httpOnly:
                        description: True if cookie is http-only.
                        type: boolean
                      sameSite:
                        description: Cookie SameSite type.
                        enum:
                          - Default
                          - Lax
                          - None
                          - Strict
                        type: string
                      priority:
                        description: Cookie Priority. Supported only in Chrome.
                        enum:
                          - High
                          - Low
                          - Medium
                        type: string
                      sourceScheme:
                        description: Cookie source scheme type. Supported only in Chrome.
                        enum:
                          - NonSecure
                          - Secure
                          - Unset
                        type: string
                      partitionKey:
                        description: >-
                          Cookie partition key. In Chrome, it matches the
                          top-level site the

                          partitioned cookie is available in. In Firefox, it
                          matches the

                          source origin in the

                          {@link
                          https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey
                          PartitionKey}.
                        anyOf:
                          - $ref: '#/components/schemas/CookiePartitionKey'
                          - type: string
                    additionalProperties: false
                    required:
                      - domain
                      - expires
                      - name
                      - path
                      - secure
                      - session
                      - size
                      - value
                  CookiePartitionKey:
                    description: Represents a cookie partition key in Chrome.
                    type: object
                    properties:
                      sourceOrigin:
                        description: >-
                          The site of the top-level URL the browser was visiting
                          at the start of the request

                          to the endpoint that set the cookie.


                          In Chrome, maps to the CDP's `topLevelSite` partition
                          key.
                        type: string
                      hasCrossSiteAncestor:
                        description: >-
                          Indicates if the cookie has any ancestors that are
                          cross-site to

                          the topLevelSite.


                          Supported only in Chrome.
                        type: boolean
                    additionalProperties: false
                    required:
                      - sourceOrigin
                  InBoundRequest:
                    type: object
                    properties:
                      headers: {}
                      status:
                        type: number
                      url:
                        type: string
                    additionalProperties: false
                    required:
                      - headers
                      - status
                      - url
                  OutBoundRequest:
                    type: object
                    properties:
                      headers: {}
                      method:
                        type: string
                      url:
                        type: string
                    additionalProperties: false
                    required:
                      - headers
                      - method
                      - url
                $schema: http://json-schema.org/draft-07/schema#
          description: The JSON response body
        '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: /chromium/scrape
      tags:
        - Scraping & Content
  /smart-scrape:
    post:
      description: >-
        Intelligently scrapes a URL using cascading strategies (HTTP fetch,
        proxy, headless browser, etc).
      parameters:
        - in: query
          name: profile
          schema:
            description: >-
              Optional name of an authentication profile to hydrate into the
              browser

              before scraping. The profile's cookies, localStorage, and
              IndexedDB

              entries are loaded into the session before navigation. Forces the

              browser strategy.
            type: string
        - in: query
          name: timeout
          schema:
            description: The timeout for the scrape operation in milliseconds
            type: number
        - in: query
          name: token
          schema:
            description: >-
              The API token for authenticating the request. Can also be provided
              in the `Authorization` header as a Bearer token. If both are
              provided, the `Authorization` header takes precedence. If no token
              is provided, the route will attempt to authenticate the request
              using any legacy authentication methods (e.g. cookie-based
              sessions) before rejecting the request as unauthorized.
            type: string
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                url:
                  description: The URL to scrape. Must be an http or https URL.
                  type: string
                formats:
                  description: >-
                    Output formats to include in the response. Accepts an array
                    of format

                    strings such as `["markdown", "screenshot"]`. When
                    `screenshot` or `pdf`

                    is included, a browser strategy is forced.

                    Mirrors the Firecrawl "formats" convention.


                    - `markdown`   – page content converted to markdown

                    - `html`       – cleaned HTML (returned by default in
                    `content`, this is a no-op convenience value)

                    - `screenshot` – full-page screenshot as base64-encoded PNG
                    (forces browser strategy)

                    - `pdf`        – PDF of the page as base64-encoded string
                    (forces browser strategy)

                    - `links`      – list of links extracted from the page
                  default:
                    - html
                  type: array
                  items:
                    enum:
                      - html
                      - links
                      - markdown
                      - pdf
                      - screenshot
                    type: string
                proxy:
                  description: >-
                    The proxy network to route the scrape through. Defaults to
                    `residential`.

                    Use `datacenter` for the cheaper datacenter pool.
                  enum:
                    - datacenter
                    - residential
                  type: string
              type: object
              required:
                - url
              example: *ref_0
            example:
              url: string
              formats:
                - html
              proxy: datacenter
      responses:
        '200':
          content:
            application/json:
              schema:
                description: An HTML payload of the scraped page content.
                type: object
                properties:
                  ok:
                    description: Whether the scrape was successful or not.
                    type: boolean
                  statusCode:
                    description: >-
                      The HTTP status code of the response, or null if the
                      scrape failed before an HTTP response was received (e.g.
                      due to a network error or captcha).
                    type: number
                  content:
                    description: >-
                      The content of the scraped page. This will be a string for
                      HTML content, or a parsed JSON object if the content type
                      is JSON. Will be null if the scrape was unsuccessful.
                    anyOf:
                      - $ref: '#/components/schemas/AnyRecord'
                      - type: string
                  contentType:
                    description: >-
                      The content type of the scraped page, or null if the
                      scrape was unsuccessful or the content type was
                      unavailable. If the scrape was successful and the content
                      type is JSON, the `content` field will contain the parsed
                      JSON object rather than a string.
                    type: string
                  headers:
                    $ref: '#/components/schemas/StringRecord'
                    description: >-
                      The HTTP response headers returned by the site, or an
                      empty object if unavailable.
                  strategy:
                    description: >-
                      The strategy that ultimately succeeded in scraping the
                      page, or the strategy that was being attempted when the
                      scrape failed.
                    type: string
                  attempted:
                    description: >-
                      The strategies that were attempted during the scrape, in
                      order.
                    type: array
                    items:
                      type: string
                  message:
                    description: >-
                      An error message describing why the scrape failed, or null
                      if the scrape was successful.
                    type: string
                  screenshot:
                    description: >-
                      A base64-encoded full-page PNG screenshot, present when
                      `"screenshot"` is in `formats` and the scrape succeeded.
                    type: string
                  pdf:
                    description: >-
                      A base64-encoded PDF of the page, present when `"pdf"` is
                      in `formats` and the scrape succeeded.
                    type: string
                  markdown:
                    description: >-
                      The page content converted to markdown, present when
                      `"markdown"` is in `formats` and the scrape succeeded.
                    type: string
                  links:
                    description: >-
                      A list of links found on the page, present when `"links"`
                      is in `formats` and the scrape succeeded.
                    type: array
                    items:
                      type: string
                additionalProperties: false
                required:
                  - attempted
                  - content
                  - contentType
                  - headers
                  - links
                  - markdown
                  - message
                  - ok
                  - pdf
                  - screenshot
                  - statusCode
                  - strategy
                definitions:
                  Record<string,unknown>:
                    type: object
                    additionalProperties: false
                  Record<string,string>:
                    type: object
                    additionalProperties: false
                $schema: http://json-schema.org/draft-07/schema#
          description: An HTML payload of the scraped page content.
        '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: /smart-scrape
      tags:
        - Scraping & Content
  /search:
    post:
      description: >-
        Search the web and optionally scrape result pages. Accepts a query,
        performs a web search via SearXNG, and optionally scrapes each result
        URL — returning structured, LLM-ready data (markdown, HTML, links, or
        screenshots).
      parameters:
        - in: query
          name: timeout
          schema:
            description: The timeout for the search operation in milliseconds.
            type: number
        - in: query
          name: token
          schema:
            description: The API token for authenticating the request.
            type: string
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                query:
                  description: The search query string.
                  type: string
                limit:
                  description: >-
                    Maximum number of results per source. Defaults to `10`.
                    Capped by plan limits.
                  type: number
                lang:
                  description: >-
                    Language code for results (e.g., `"en"`, `"es"`, `"de"`).
                    Defaults to `"en"`.
                  type: string
                location:
                  description: >-
                    City or region to narrow geo-targeting (e.g., `"San
                    Francisco"`). Use with `country`.
                  type: string
                country:
                  description: >-
                    ISO 3166-1 alpha-2 country code for geo-targeted results
                    (e.g., `"us"`, `"gb"`, `"de"`).
                  type: string
                proxy:
                  description: >-
                    Proxy network to route result scraping through:
                    `"residential"` (default) or `"datacenter"`.
                  enum:
                    - datacenter
                    - residential
                  type: string
                tbs:
                  description: >-
                    Time-based filter. Accepts `"day"`, `"week"`, `"month"`,
                    `"year"`, or raw Google TBS syntax (`"qdr:d"`, `"qdr:w"`,
                    `"qdr:m"`, `"qdr:y"`).
                  enum:
                    - day
                    - month
                    - qdr:d
                    - qdr:m
                    - qdr:w
                    - qdr:y
                    - week
                    - year
                  type: string
                categories:
                  description: >-
                    Content category filters. Restricts results to `"github"`
                    repos, `"research"` papers, or `"pdf"` documents.
                  type: array
                  items:
                    enum:
                      - github
                      - pdf
                      - research
                    type: string
                sources:
                  description: >-
                    Sources to search. Defaults to `["web"]`. Also supports
                    `"news"` and `"images"`.
                  type: array
                  items:
                    enum:
                      - images
                      - news
                      - web
                    type: string
                timeout:
                  description: Request timeout in milliseconds.
                  type: number
                scrapeOptions:
                  description: >-
                    When provided, fetches and processes each result URL into
                    structured content.
                  type: object
                  properties:
                    formats:
                      type: array
                      items:
                        enum:
                          - html
                          - links
                          - markdown
                          - screenshot
                        type: string
                    stripNonContentTags:
                      type: boolean
                    onlyMainContent:
                      type: boolean
                    removeBase64Images:
                      type: boolean
                    includeTags:
                      type: array
                      items:
                        type: string
                    excludeTags:
                      type: array
                      items:
                        type: string
                  additionalProperties: false
                  required:
                    - formats
              type: object
              required:
                - query
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/SearchResponseData'
                  totalResults:
                    type: number
                  error:
                    type: string
                additionalProperties: false
                required:
                  - data
                  - success
                  - totalResults
                definitions:
                  SearchResponseData:
                    type: object
                    properties:
                      web:
                        type: array
                        items:
                          $ref: '#/components/schemas/WebSearchResult'
                      news:
                        type: array
                        items:
                          $ref: '#/components/schemas/NewsSearchResult'
                      images:
                        type: array
                        items:
                          $ref: '#/components/schemas/ImageSearchResult'
                    additionalProperties: false
                  WebSearchResult:
                    type: object
                    properties:
                      title:
                        type: string
                      url:
                        type: string
                      description:
                        type: string
                      position:
                        type: number
                      markdown:
                        type: string
                      html:
                        type: string
                      links:
                        type: array
                        items:
                          type: string
                      screenshot:
                        type: string
                      metadata:
                        type: object
                        properties:
                          statusCode:
                            type: number
                          strategy:
                            type: string
                          error:
                            type: string
                        additionalProperties: false
                        required:
                          - statusCode
                    additionalProperties: false
                    required:
                      - description
                      - title
                      - url
                  NewsSearchResult:
                    type: object
                    properties:
                      date:
                        type: string
                      imageUrl:
                        type: string
                      title:
                        type: string
                      url:
                        type: string
                      description:
                        type: string
                      position:
                        type: number
                      markdown:
                        type: string
                      html:
                        type: string
                      links:
                        type: array
                        items:
                          type: string
                      screenshot:
                        type: string
                      metadata:
                        type: object
                        properties:
                          statusCode:
                            type: number
                          strategy:
                            type: string
                          error:
                            type: string
                        additionalProperties: false
                        required:
                          - statusCode
                    additionalProperties: false
                    required:
                      - description
                      - title
                      - url
                  ImageSearchResult:
                    type: object
                    properties:
                      title:
                        type: string
                      imageUrl:
                        type: string
                      imageWidth:
                        type: number
                      imageHeight:
                        type: number
                      url:
                        type: string
                      position:
                        type: number
                    additionalProperties: false
                $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: /search
      tags:
        - Scraping & Content
  /map:
    post:
      description: |-
        Primarily discovers URLs from the site's sitemap, supplemented
        with link extraction from the page via the smart-scrape strategy
        pipeline (HTTP-first, browser fallback for JS-rendered pages).
        Use the search parameter to order results by relevance.
      parameters:
        - in: query
          name: timeout
          schema:
            description: Request timeout in milliseconds
            type: number
        - in: query
          name: token
          schema:
            description: API authentication token
            type: string
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                url:
                  description: The base URL to start mapping from (required)
                  type: string
                search:
                  description: Search query to order results by relevance
                  type: string
                limit:
                  description: 'Maximum number of links to return (default: 5000, max: 5000)'
                  type: number
                timeout:
                  description: Request timeout in milliseconds
                  type: number
                sitemap:
                  description: >-
                    Controls sitemap behavior: "include" (default), "skip",
                    "only"
                  enum:
                    - include
                    - only
                    - skip
                  type: string
                includeSubdomains:
                  description: 'Whether to include URLs from subdomains (default: true)'
                  type: boolean
                ignoreQueryParameters:
                  description: 'Exclude URLs with query parameters (default: true)'
                  type: boolean
                location:
                  description: Geo-targeting settings
                  type: object
                  properties:
                    country:
                      description: >-
                        ISO 3166-1 alpha-2 country code for proxy routing (e.g.,
                        `"us"`, `"gb"`, `"de"`). Defaults to `"us"`.
                      type: string
                    languages:
                      description: >-
                        Preferred language codes for the request (e.g., `["en",
                        "fr"]`).
                      type: array
                      items:
                        type: string
                  additionalProperties: false
                proxy:
                  description: >-
                    Proxy network to route through: `"residential"` (default) or
                    `"datacenter"`.
                  enum:
                    - datacenter
                    - residential
                  type: string
              type: object
              required:
                - url
              example: *ref_0
            example:
              url: string
              search: string
              limit: 0
              timeout: 0
              sitemap: include
              includeSubdomains: true
              ignoreQueryParameters: true
              location:
                country: string
                languages:
                  - string
              proxy: datacenter
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                description: >-
                  An array of URLs discovered on the target page, including
                  links found in the HTML, sitemap entries, and any other
                  discoverable URLs.
          description: An array of discovered URLs from the target page and its sitemap.
        '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: /map
      tags:
        - Scraping & Content
  /edge/content:
    post:
      description: >-
        Given a `url` or `html` field, loads the page in Edge and returns the
        fully rendered HTML.
      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: launch
          schema:
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                addScriptTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  anyOf:
                    - $ref: '#/components/schemas/Credentials'
                    - type: 'null'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                emulateMediaType:
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  type: string
                rejectRequestPattern:
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                            $ref: '#/components/schemas/AnyRecord'
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                setExtraHTTPHeaders:
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  description: Whether or not to allow JavaScript to run on the page.
                  type: boolean
                url:
                  type: string
                userAgent:
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      description: >-
                        Used to specify User Agent Client Hints to emulate. See
                        https://wicg.github.io/ua-client-hints

                        Missing optional values will be filled in by the target
                        with what it would normally use.
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  anyOf:
                    - $ref: '#/components/schemas/Viewport'
                    - type: 'null'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  type: number
              type: object
              example: *ref_0
            example:
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            text/html:
              schema:
                description: |-
                  An HTML payload of the website or HTML after JavaScript
                  parsing and execution.
                type: string
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            An HTML payload of the website or HTML after JavaScript
            parsing and execution.
        '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: /edge/content
      tags:
        - Scraping & Content
  /edge/scrape:
    post:
      description: >-
        Returns text, HTML, and metadata from a given list of CSS selectors
        against the rendered DOM (Edge).

        Debugging information is available by sending in the appropriate flags
        in the "debugOpts"

        property. Responds with an array of JSON objects.
      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: launch
          schema:
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                addScriptTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  anyOf:
                    - $ref: '#/components/schemas/Credentials'
                    - type: 'null'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                debugOpts:
                  $ref: '#/components/schemas/ScrapeDebugOptions'
                elements:
                  type: array
                  items:
                    $ref: '#/components/schemas/ScrapeElementSelector'
                emulateMediaType:
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  type: string
                rejectRequestPattern:
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                            $ref: '#/components/schemas/AnyRecord'
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                setExtraHTTPHeaders:
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  type: boolean
                url:
                  type: string
                userAgent:
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      description: >-
                        Used to specify User Agent Client Hints to emulate. See
                        https://wicg.github.io/ua-client-hints

                        Missing optional values will be filled in by the target
                        with what it would normally use.
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  anyOf:
                    - $ref: '#/components/schemas/Viewport'
                    - type: 'null'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  type: number
              type: object
              required:
                - elements
              example: *ref_1
            example:
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              debugOpts:
                console: true
                cookies: true
                html: true
                network: true
                screenshot: true
              elements:
                - selector: string
                  timeout: 0
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            application/json:
              schema:
                description: The JSON response body
                type: object
                properties:
                  data:
                    anyOf:
                      - type: array
                        items:
                          type: object
                          properties:
                            results:
                              type: array
                              items:
                                type: object
                                properties:
                                  attributes:
                                    description: A list of HTML attributes of the element
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        name:
                                          description: >-
                                            The name of the HTML attribute for the
                                            element
                                          type: string
                                        value:
                                          description: >-
                                            The value of the HTML attribute for the
                                            element
                                          type: string
                                      additionalProperties: false
                                      required:
                                        - name
                                        - value
                                  height:
                                    description: The height the element
                                    type: number
                                  html:
                                    description: The HTML the element
                                    type: string
                                  left:
                                    description: >-
                                      The amount of pixels from the left of the
                                      page
                                    type: number
                                  text:
                                    description: The text the element
                                    type: string
                                  top:
                                    description: >-
                                      The amount of pixels from the top of the
                                      page
                                    type: number
                                  width:
                                    description: The width the element
                                    type: number
                                additionalProperties: false
                                required:
                                  - attributes
                                  - height
                                  - html
                                  - left
                                  - text
                                  - top
                                  - width
                            selector:
                              description: The DOM selector of the element
                              type: string
                          additionalProperties: false
                          required:
                            - results
                            - selector
                      - type: 'null'
                  debug:
                    description: When debugOpts options are present, results are here
                    anyOf:
                      - type: object
                        properties:
                          console:
                            description: A list of console messages from the browser
                            type: array
                            items:
                              type: string
                          cookies:
                            description: List of cookies for the site or null
                            anyOf:
                              - type: array
                                items:
                                  $ref: '#/components/schemas/Cookie'
                              - type: 'null'
                          html:
                            description: The HTML string of the website or null
                            type:
                              - 'null'
                              - string
                          network:
                            type: object
                            properties:
                              inbound:
                                type: array
                                items:
                                  $ref: '#/components/schemas/InBoundRequest'
                              outbound:
                                type: array
                                items:
                                  $ref: '#/components/schemas/OutBoundRequest'
                            additionalProperties: false
                            required:
                              - inbound
                              - outbound
                          screenshot:
                            description: A base64-encoded string of the site or null
                            type:
                              - 'null'
                              - string
                        additionalProperties: false
                        required:
                          - console
                          - cookies
                          - html
                          - network
                          - screenshot
                      - type: 'null'
                additionalProperties: false
                required:
                  - data
                  - debug
                definitions:
                  Cookie:
                    description: Represents a cookie object.
                    type: object
                    properties:
                      path:
                        description: Cookie path.
                        type: string
                      expires:
                        description: >-
                          Cookie expiration date as the number of seconds since
                          the UNIX epoch. Set to `-1` for

                          session cookies
                        type: number
                      size:
                        description: Cookie size.
                        type: number
                      secure:
                        description: True if cookie is secure.
                        type: boolean
                      session:
                        description: True in case of session cookie.
                        type: boolean
                      partitionKeyOpaque:
                        description: >-
                          True if cookie partition key is opaque. Supported only
                          in Chrome.
                        type: boolean
                      name:
                        description: Cookie name.
                        type: string
                      value:
                        description: Cookie value.
                        type: string
                      domain:
                        description: Cookie domain.
                        type: string
                      httpOnly:
                        description: True if cookie is http-only.
                        type: boolean
                      sameSite:
                        description: Cookie SameSite type.
                        enum:
                          - Default
                          - Lax
                          - None
                          - Strict
                        type: string
                      priority:
                        description: Cookie Priority. Supported only in Chrome.
                        enum:
                          - High
                          - Low
                          - Medium
                        type: string
                      sourceScheme:
                        description: Cookie source scheme type. Supported only in Chrome.
                        enum:
                          - NonSecure
                          - Secure
                          - Unset
                        type: string
                      partitionKey:
                        description: >-
                          Cookie partition key. In Chrome, it matches the
                          top-level site the

                          partitioned cookie is available in. In Firefox, it
                          matches the

                          source origin in the

                          {@link
                          https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey
                          PartitionKey}.
                        anyOf:
                          - $ref: '#/components/schemas/CookiePartitionKey'
                          - type: string
                    additionalProperties: false
                    required:
                      - domain
                      - expires
                      - name
                      - path
                      - secure
                      - session
                      - size
                      - value
                  CookiePartitionKey:
                    description: Represents a cookie partition key in Chrome.
                    type: object
                    properties:
                      sourceOrigin:
                        description: >-
                          The site of the top-level URL the browser was visiting
                          at the start of the request

                          to the endpoint that set the cookie.


                          In Chrome, maps to the CDP's `topLevelSite` partition
                          key.
                        type: string
                      hasCrossSiteAncestor:
                        description: >-
                          Indicates if the cookie has any ancestors that are
                          cross-site to

                          the topLevelSite.


                          Supported only in Chrome.
                        type: boolean
                    additionalProperties: false
                    required:
                      - sourceOrigin
                  InBoundRequest:
                    type: object
                    properties:
                      headers: {}
                      status:
                        type: number
                      url:
                        type: string
                    additionalProperties: false
                    required:
                      - headers
                      - status
                      - url
                  OutBoundRequest:
                    type: object
                    properties:
                      headers: {}
                      method:
                        type: string
                      url:
                        type: string
                    additionalProperties: false
                    required:
                      - headers
                      - method
                      - url
                $schema: http://json-schema.org/draft-07/schema#
          description: The JSON response body
        '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: /edge/scrape
      tags:
        - Scraping & Content
  /chromium/performance:
    post:
      description: >-
        Run lighthouse performance audits with a supplied "url" in your JSON
        payload.


        **Note:** Also available at `/performance` as a convenience alias.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                budgets:
                  type: array
                  items:
                    type: object
                    properties: {}
                    additionalProperties: true
                config:
                  type: object
                  properties: {}
                  additionalProperties: true
                url:
                  type: string
              type: object
              required:
                - url
              example: *ref_0
            example:
              budgets:
                - {}
              config: {}
              url: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: |-
                  The response of the lighthouse stats. Response objects are
                  determined by the type of budgets and config in the POST
                  JSON body
                type: object
                properties: {}
                additionalProperties: true
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            The response of the lighthouse stats. Response objects are
            determined by the type of budgets and config in the POST
            JSON body
        '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: /chromium/performance
      tags:
        - Scraping & Content
  /edge/performance:
    post:
      description: >-
        Run lighthouse performance audits with a supplied "url" in your JSON
        payload.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                budgets:
                  type: array
                  items:
                    type: object
                    properties: {}
                    additionalProperties: true
                config:
                  type: object
                  properties: {}
                  additionalProperties: true
                url:
                  type: string
              type: object
              required:
                - url
              example: *ref_0
            example:
              budgets:
                - {}
              config: {}
              url: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: |-
                  The response of the lighthouse stats. Response objects are
                  determined by the type of budgets and config in the POST
                  JSON body
                type: object
                properties: {}
                additionalProperties: true
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            The response of the lighthouse stats. Response objects are
            determined by the type of budgets and config in the POST
            JSON body
        '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: /edge/performance
      tags:
        - Scraping & Content
  /chromium/function:
    post:
      description: >-
        Executes a Puppeteer or Playwright script in the browser context and
        returns the result.

        Browserless sets up a blank page, injects your puppeteer code, and runs
        it.

        You can optionally load external libraries via the "import" module that
        are meant for browser usage.

        Values returned from the function are checked and an appropriate
        content-type and response is sent back

        to your HTTP call.


        **Note:** Also available at `/function` as a convenience alias.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JSONSchema'
          application/javascript:
            schema:
              type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                description: >-
                  Responses are determined by the returned value of the function

                  itself. Binary responses (PDF's, screenshots) are returned
                  back

                  as binary data, and primitive JavaScript values are returned
                  back

                  by type (HTML data is "text/html", Objects are
                  "application/json")
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            Responses are determined by the returned value of the function
            itself. Binary responses (PDF's, screenshots) are returned back
            as binary data, and primitive JavaScript values are returned back
            by type (HTML data is "text/html", Objects are "application/json")
        '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: /chromium/function
      tags:
        - Functions & Downloads
  /chromium/download:
    post:
      description: >-
        Runs a Puppeteer or Playwright script and returns any files the browser
        downloaded during execution.

        the execution of puppeteer code, which is ran inside context of the
        browser.

        Browserless sets up a blank page, a fresh download directory, injects
        your puppeteer code, and then executes it.

        You can load external libraries via the "import" syntax, and import
        ESM-style modules

        that are written for execution inside of the browser. Once your script
        is finished, any

        downloaded files from Chromium are returned back with the appropriate
        content-type header.


        **Note:** Also available at `/download` as a convenience alias.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JSONSchema'
          application/javascript:
            schema:
              type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                description: >-
                  Responses are determined by the returned value of the
                  downloads

                  themselves, so there isn't a static response type for this
                  API.
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            Responses are determined by the returned value of the downloads
            themselves, so there isn't a static response type for this API.
        '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: /chromium/download
      tags:
        - Functions & Downloads
  /edge/function:
    post:
      description: >-
        Executes a Puppeteer or Playwright script in the Edge browser context
        and returns the result.

        Browserless sets up a blank page, injects your puppeteer code, and runs
        it.

        You can optionally load external libraries via the "import" module that
        are meant for browser usage.

        Values returned from the function are checked and an appropriate
        content-type and response is sent back

        to your HTTP call.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JSONSchema'
          application/javascript:
            schema:
              type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                description: >-
                  Responses are determined by the returned value of the function

                  itself. Binary responses (PDF's, screenshots) are returned
                  back

                  as binary data, and primitive JavaScript values are returned
                  back

                  by type (HTML data is "text/html", Objects are
                  "application/json")
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            Responses are determined by the returned value of the function
            itself. Binary responses (PDF's, screenshots) are returned back
            as binary data, and primitive JavaScript values are returned back
            by type (HTML data is "text/html", Objects are "application/json")
        '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: /edge/function
      tags:
        - Functions & Downloads
  /edge/download:
    post:
      description: >-
        Runs a Puppeteer or Playwright script in Edge and returns any files the
        browser downloaded during execution.

        the execution of puppeteer code, which is ran inside context of the
        browser.

        Browserless sets up a blank page, a fresh download directory, injects
        your puppeteer code, and then executes it.

        You can load external libraries via the "import" syntax, and import
        ESM-style modules

        that are written for execution inside of the browser. Once your script
        is finished, any

        downloaded files from Chromium are returned back with the appropriate
        content-type header.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JSONSchema'
          application/javascript:
            schema:
              type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                description: >-
                  Responses are determined by the returned value of the
                  downloads

                  themselves, so there isn't a static response type for this
                  API.
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            Responses are determined by the returned value of the downloads
            themselves, so there isn't a static response type for this API.
        '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: /edge/download
      tags:
        - Functions & Downloads
  /chromium/export:
    post:
      description: >-
        Exports a webpage to a PDF or image format. This API is useful for
        generating reports, screenshots, or PDFs of web pages.


        **Note:** Also available at `/export` as a convenience alias.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            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:
          application/json:
            schema:
              properties:
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless will attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                url:
                  description: The URL of the site you want to archive.
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    An optional goto parameter object for considering when the
                    page is done loading.
                waitForEvent:
                  description: >-
                    Options for waiting for a specific event to be fired on the
                    page.
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  description: Options for waiting for a JavaScript function to execute.
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  description: >-
                    Options for waiting for a specific CSS selector to appear on
                    the page.
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  description: >-
                    The amount of time in milliseconds to wait before
                    proceeding.
                  type: number
                headers:
                  description: >-
                    An object containing additional HTTP headers to send with
                    every request.
                  type: object
                  additionalProperties:
                    type: string
                includeResources:
                  description: >-
                    Whether to include all linked resources (images, CSS, JS) in
                    a zip file.

                    When true, the response will be a zip file containing the
                    HTML and all resources.

                    When false or not provided, the response will be the raw
                    content (default behavior).
                  type: boolean
              type: object
              required:
                - url
              example: *ref_0
            example:
              bestAttempt: true
              url: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
              headers: {}
              includeResources: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  html:
                    description: The HTML content of the page.
                    type: string
                additionalProperties: false
                required:
                  - html
                $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: /chromium/export
      tags:
        - Functions & Downloads
  /session:
    post:
      description: >-
        Creates a new browser session with the specified parameters. The session
        can be used for persistent browser connections

        with well-defined lifetimes and reconnection semantics. BrowserQL
        support is only available for stealth sessions.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                ttl:
                  description: >-
                    The time-to-live (TTL) for the session in milliseconds. Once
                    reached, will be forcefully terminated

                    and all files and processes will be cleaned up. Must be a
                    non-negative number greater than 0.
                  type: number
                processKeepAlive:
                  description: >-
                    An optional time, in milliseconds, to keep the underlying
                    browser process alive after a connection to the session
                    closes.

                    If a connection happens within the keep-alive window, the
                    browser process will remain running and the session can be
                    reconnected to.

                    If a connection happens after the keep-alive window has
                    expired, a new browser process will be launched for the
                    session, with the prior

                    session data. Defaults to 0 (no keep-alive).
                  type: number
                stealth:
                  description: >-
                    Whether or not to enable advanced stealth mode. Defaults to
                    false.
                  type: boolean
                blockAds:
                  description: Whether or not to enable ad-blocking. Defaults to false.
                  type: boolean
                headless:
                  description: |-
                    Whether the browser should be launched in headless mode.
                    Ignored if `stealth` is true, defaults to "true".
                  type: boolean
                args:
                  description: |-
                    An array of command-line arguments to pass to the browser.
                    Defaults to an empty array.
                  type: array
                  items:
                    type: string
                browser:
                  description: >-
                    The type of browser to use for the session.

                    'stealth' uses the Brave browser with advanced
                    anti-detection. Defaults to 'chromium'.
                  enum:
                    - chrome
                    - chromium
                    - stealth
                  type: string
                url:
                  description: >-
                    The underlying page URL you're attempting to automate. Some
                    pages may

                    required special handling in order to work correctly or
                    unblock.

                    This is not required, but can be useful or required for
                    certain sites.
                  type: string
                proxy:
                  description: >-
                    Proxy Parameters for the session if desired.

                    If not specified, the session will use the default network
                    settings.
                  type: object
                  properties:
                    type:
                      description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
                      enum:
                        - datacenter
                        - residential
                      type: string
                    sticky:
                      description: >-
                        Whether or not to use the same IP address for all
                        proxied requests. Defaults to true
                      type: boolean
                    country:
                      description: >-
                        The country to proxy through. Defaults to 'us' or United
                        States
                      type: string
                    city:
                      description: The city to proxy through.
                      type: string
                    state:
                      description: The state to proxy through.
                      type: string
                    preset:
                      description: >-
                        Preset code for website-specific proxy configurations
                        (e.g., 'px_gov01' for government sites)
                      type: string
                  additionalProperties: false
                replay:
                  description: >-
                    Whether to enable session recording for replay.

                    When true, the session will be recorded and can be replayed
                    later.
                  type: boolean
                extensions:
                  description: >-
                    An array of extension IDs to load into the browser session.

                    Extensions must be previously uploaded to the browserless
                    extension storage.

                    This allows sessions to start with extensions pre-loaded
                    without specifying

                    them in launch arguments at connection time.
                  type: array
                  items:
                    type: string
                profile:
                  description: >-
                    Optional name of an authentication profile to use as initial
                    browser state.

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

                    CDP before your code runs. sessionStorage is intentionally
                    not restored —

                    it is tab-scoped and stale values break OAuth/CSRF flows.
                    Changes during

                    the session do not affect the source profile.
                  type: string
                integrationId:
                  description: >-
                    Optional 1Password integration id. When set,
                    Browserless.loadSecret can

                    resolve credentials from this integration during the
                    session. Validated at

                    session creation; a missing or expired integration rejects
                    the request.
                  type: string
                credentials:
                  description: >-
                    Maps caller aliases to 1Password op:// references, e.g.

                    { "password": "op://Prod/GitHub/password" }. Reference
                    strings are not

                    secret; resolved values are never stored on the session.
                  type: object
                  additionalProperties:
                    type: string
                allowedDomains:
                  description: >-
                    Optionally narrows the integration's allowed-domain list for
                    this session.

                    Cannot widen it — the effective list is the intersection of
                    the two.
                  type: array
                  items:
                    type: string
              type: object
              required:
                - ttl
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: The ID of the session
                    type: string
                  connect:
                    description: >-
                      The fully-qualified URL to connect CDP-based libraries to
                      the session
                    type: string
                  ttl:
                    description: The total time of life in milliseconds
                    type: number
                  stop:
                    description: >-
                      The fully qualified URL to stop and remove the session
                      with a DELETE method.
                    type: string
                  browserQL:
                    description: >-
                      The fully-qualified URL to run BrowserQL queries against
                      the session
                    type: string
                  cloudEndpointId:
                    description: >-
                      The encrypted cloud endpoint ID for the session when ran
                      in the browserless cloud.

                      This is a cloud-specific property and is only present when
                      using browserless cloud.
                    type: string
                additionalProperties: false
                required:
                  - browserQL
                  - cloudEndpointId
                  - connect
                  - id
                  - stop
                  - ttl
                $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: /session
      tags:
        - Sessions & Connections
      operationId: session-create
  /json/new:
    put:
      description: >-
        Returns a JSON payload that acts as a pass-through to the DevTools
        /json/new HTTP API in Chromium.

        Browserless mocks this payload so that remote clients can connect to the
        underlying "webSocketDebuggerUrl"

        which will cause Browserless to start the browser and proxy that request
        into a blank page.
      parameters: []
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    description: The description of the target. Generally the page's title.
                    type: string
                  devtoolsFrontendUrl:
                    description: The fully-qualified URL of the Devtools inspector app.
                    type: string
                  id:
                    description: A Unique Id for the underlying target.
                    type: string
                  title:
                    description: >-
                      The title of the target. For pages this is the page's
                      title.
                    type: string
                  type:
                    description: The type of target, generally "page" or "background_page".
                    type: string
                  url:
                    description: The current URL the target is consuming or visiting.
                    type: string
                  webSocketDebuggerUrl:
                    description: >-
                      The target or page's WebSocket Debugger URL. Primarily
                      used for legacy

                      libraries to connect and inspect or remote automate this
                      target.
                    type: string
                additionalProperties: false
                required:
                  - description
                  - devtoolsFrontendUrl
                  - id
                  - title
                  - type
                  - url
                  - webSocketDebuggerUrl
                $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: /json/new
      tags:
        - Sessions & Connections
  /json/version:
    get:
      description: >-
        Returns a JSON payload that acts as a pass-through to the DevTools
        /json/version protocol in Chrome and Chromium.
      parameters: []
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    description: The description of the target. Generally the page's title.
                    type: string
                  devtoolsFrontendUrl:
                    description: The fully-qualified URL of the Devtools inspector app.
                    type: string
                  id:
                    description: A Unique Id for the underlying target.
                    type: string
                  title:
                    description: >-
                      The title of the target. For pages this is the page's
                      title.
                    type: string
                  type:
                    description: The type of target, generally "page" or "background_page".
                    type: string
                  url:
                    description: The current URL the target is consuming or visiting.
                    type: string
                  webSocketDebuggerUrl:
                    description: >-
                      The target or page's WebSocket Debugger URL. Primarily
                      used for legacy

                      libraries to connect and inspect or remote automate this
                      target.
                    type: string
                additionalProperties: false
                required:
                  - description
                  - devtoolsFrontendUrl
                  - id
                  - title
                  - type
                  - url
                  - webSocketDebuggerUrl
                $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: /json/version
      tags:
        - Sessions & Connections
  /json/protocol:
    get:
      description: Returns Protocol JSON meta-data that Chrome and Chromium come with.
      parameters: []
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties: {}
                additionalProperties: true
                $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: /json/protocol
      tags:
        - Sessions & Connections
  /active:
    get:
      description: >-
        Returns a simple "204" HTTP code, with no response, indicating that the
        service itself is up and running.

        Useful for liveliness probes or other external checks.
      parameters: []
      requestBody:
        content: {}
      responses:
        '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: /active
      tags:
        - Browser Management
  /kill/+([0-9a-zA-Z-_]):
    get:
      description: Kill running sessions based on BrowserId or TrackingId.
      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: browserId
          schema:
            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: string
                $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: /kill/+([0-9a-zA-Z-_])
      tags:
        - Browser Management
  /meta:
    get:
      description: >-
        Returns a JSON payload of the current system versions, including the
        core API version.
      parameters: []
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    description: The semantic version of the Browserless API
                    type: string
                  chromium:
                    description: >-
                      The version of Chromium installed, or null if not
                      installed
                    type:
                      - 'null'
                      - string
                  webkit:
                    description: The version of Webkit installed, or null if not installed
                    type:
                      - 'null'
                      - string
                  firefox:
                    description: The version of Firefox installed, or null if not installed
                    type:
                      - 'null'
                      - string
                  playwright:
                    description: The supported version(s) of puppeteer
                    type: array
                    items:
                      type: string
                  puppeteer:
                    description: The supported version(s) of playwright
                    type: array
                    items:
                      type: string
                additionalProperties: false
                required:
                  - chromium
                  - firefox
                  - playwright
                  - puppeteer
                  - version
                  - webkit
                $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: /meta
      tags:
        - Browser Management
  /browser/*:
    delete:
      description: >-
        Terminates a browser instance by browserId. The browser must belong to
        the authenticated user.
      parameters: []
      requestBody:
        content: {}
      responses:
        '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: /browser/*
      tags:
        - Browser Management
  /crawl:
    get:
      description: >-
        List all crawl jobs for the authenticated token. Returns an array of
        crawl summaries with status, progress counters, and timestamps. Supports
        cursor-based pagination via the `nextCursor` field.
      parameters:
        - in: query
          name: cursor
          schema:
            description: Cursor for fetching the next page of results.
            type: string
        - in: query
          name: limit
          schema:
            description: Maximum number of crawls to return per page (1–100, default 20).
            type: number
        - in: query
          name: status
          schema:
            description: >-
              Filter crawls by status: in-progress, completed, failed, or
              cancelled.
            type: string
        - in: query
          name: token
          schema:
            description: The API token for authenticating the request.
            type: string
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  crawls:
                    type: array
                    items:
                      $ref: '#/components/schemas/CrawlListItem'
                  nextCursor:
                    type: string
                additionalProperties: false
                required:
                  - crawls
                  - nextCursor
                definitions:
                  CrawlListItem:
                    type: object
                    properties:
                      id:
                        type: string
                      url:
                        type: string
                      status:
                        $ref: '#/components/schemas/CrawlStatus'
                      total:
                        type: number
                      completed:
                        type: number
                      createdAt:
                        type: string
                      completedAt:
                        type: string
                    additionalProperties: false
                    required:
                      - completed
                      - completedAt
                      - createdAt
                      - id
                      - status
                      - total
                      - url
                  CrawlStatus:
                    enum:
                      - cancelled
                      - completed
                      - failed
                      - in-progress
                    type: string
                $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: /crawl
      tags:
        - Crawling
      operationId: crawl-list
    post:
      description: >-
        Start an asynchronous crawl job that spiders a website and scrapes every
        discovered page. Returns a crawl ID and status URL for polling results
        via GET /crawl/{id}. Supports depth control, path filtering, sitemap
        strategies, and webhook notifications.
      parameters:
        - in: query
          name: profile
          schema:
            description: >-
              Optional name of an authentication profile to hydrate into the
              browser

              before each page is scraped. The profile's cookies, localStorage,
              and

              IndexedDB entries are loaded into the session before navigation.
              Forces

              the browser strategy for every page.
            type: string
        - in: query
          name: token
          schema:
            description: The API token for authenticating the request.
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                url:
                  description: The URL to crawl. Must be a valid http or https URL.
                  type: string
                limit:
                  description: >-
                    Maximum number of pages to crawl. Clamped to your plan's
                    limit.
                  default: 100
                  minimum: 1
                  type: number
                maxDepth:
                  description: Maximum link-follow depth from the root URL.
                  default: 5
                  minimum: 0
                  type: number
                maxRetries:
                  description: Number of retry attempts per failed page.
                  default: 1
                  minimum: 0
                  type: number
                allowExternalLinks:
                  description: Whether to follow links to external domains.
                  default: false
                  type: boolean
                allowSubdomains:
                  description: Whether to follow links to subdomains of the root URL.
                  default: false
                  type: boolean
                sitemap:
                  description: Sitemap handling strategy.
                  default: auto
                  enum:
                    - auto
                    - force
                    - skip
                  type: string
                includePaths:
                  description: Regex patterns for URL paths to include.
                  default: []
                  type: array
                  items:
                    type: string
                excludePaths:
                  description: Regex patterns for URL paths to exclude.
                  default: []
                  type: array
                  items:
                    type: string
                delay:
                  description: Delay between requests in milliseconds.
                  default: 200
                  minimum: 0
                  type: number
                scrapeOptions:
                  description: Options controlling how each page is scraped.
                  type: object
                  properties:
                    formats:
                      description: Output formats for scraped content.
                      default:
                        - markdown
                      type: array
                      items:
                        enum:
                          - html
                          - markdown
                          - rawText
                        type: string
                    onlyMainContent:
                      description: Whether to extract only the main content of the page.
                      default: true
                      type: boolean
                    includeTags:
                      description: HTML tag selectors to include.
                      default: []
                      type: array
                      items:
                        type: string
                    excludeTags:
                      description: HTML tag selectors to exclude.
                      default: []
                      type: array
                      items:
                        type: string
                    waitFor:
                      description: Time in ms to wait after page load before scraping.
                      default: 0
                      minimum: 0
                      type: number
                    headers:
                      description: Custom HTTP headers to send with each request.
                      type: object
                      additionalProperties:
                        type: string
                    timeout:
                      description: Navigation timeout in milliseconds.
                      default: 150000
                      minimum: 1000
                      maximum: 180000
                      type: number
                    proxy:
                      description: >-
                        Proxy network to route page fetches through:
                        `"residential"` (default)

                        or `"datacenter"`.
                      enum:
                        - datacenter
                        - residential
                      type: string
                  additionalProperties: false
                webhook:
                  description: Webhook configuration for crawl event notifications.
                  type: object
                  properties:
                    url:
                      description: The HTTPS URL to send webhook events to.
                      type: string
                    events:
                      description: Which events to send.
                      default:
                        - completed
                      type: array
                      items:
                        enum:
                          - completed
                          - failed
                          - page
                        type: string
                  additionalProperties: false
                  required:
                    - url
              type: object
              required:
                - url
              example: *ref_0
            example:
              url: string
              limit: 100
              maxDepth: 5
              maxRetries: 1
              allowExternalLinks: false
              allowSubdomains: false
              sitemap: auto
              includePaths:
                - string
              excludePaths:
                - string
              delay: 200
              scrapeOptions:
                formats:
                  - html
                onlyMainContent: true
                includeTags:
                  - string
                excludeTags:
                  - string
                waitFor: 0
                headers: {}
                timeout: 150000
                proxy: datacenter
              webhook:
                url: string
                events:
                  - completed
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  id:
                    type: string
                  url:
                    type: string
                additionalProperties: false
                required:
                  - id
                  - success
                  - url
                $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: /crawl
      tags:
        - Crawling
      operationId: crawl-start
  /crawl/*:
    delete:
      description: >-
        Cancel a running crawl job by its ID. Any pages already completed remain
        available for retrieval. Returns a 409 if the crawl is already in a
        terminal state.
      parameters:
        - in: query
          name: token
          schema:
            description: The API token for authenticating the request.
            type: string
      requestBody:
        content: {}
      responses:
        '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: /crawl/*
      tags:
        - Crawling
      operationId: crawl-cancel
    get:
      description: >-
        Get the status of a crawl job and its paginated page results. Returns
        progress counters, per-page metadata with content URLs, and a `next` URL
        for offset-based pagination via the `skip` parameter.
      parameters:
        - in: query
          name: skip
          schema:
            description: The number of pages to skip for pagination.
            type: number
        - in: query
          name: token
          schema:
            description: The API token for authenticating the request.
            type: string
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/components/schemas/CrawlStatus'
                  total:
                    type: number
                  completed:
                    type: number
                  failed:
                    type: number
                  expiresAt:
                    type: string
                  next:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CrawlPageResponse'
                additionalProperties: false
                required:
                  - completed
                  - data
                  - expiresAt
                  - failed
                  - next
                  - status
                  - total
                definitions:
                  CrawlStatus:
                    enum:
                      - cancelled
                      - completed
                      - failed
                      - in-progress
                    type: string
                  CrawlPageResponse:
                    type: object
                    properties:
                      status:
                        $ref: '#/components/schemas/PageStatus'
                      contentUrl:
                        type: string
                      metadata:
                        type: object
                        properties:
                          title:
                            type: string
                          description:
                            type: string
                          language:
                            type: string
                          scrapedAt:
                            type: string
                          sourceURL:
                            type: string
                          statusCode:
                            type: number
                          error:
                            type: string
                        additionalProperties: false
                        required:
                          - description
                          - error
                          - language
                          - scrapedAt
                          - sourceURL
                          - statusCode
                          - title
                    additionalProperties: false
                    required:
                      - contentUrl
                      - metadata
                      - status
                  PageStatus:
                    enum:
                      - cancelled
                      - completed
                      - failed
                      - in-progress
                      - queued
                    type: string
                $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: /crawl/*
      tags:
        - Crawling
      operationId: crawl-status
  /unblock:
    post:
      description: |-
        Unblocks the provided URL from being blocked due to bot detection.
        Returns a payload of Cookies, HTML, a base64 encoded screenshot,
        and a "browserWSEndpoint" to allow connecting to the browser when
        specified in the JSON Payload. Only supports CDP or Puppeteer
        like libraries when connecting to the "browserWSEndpoint".

        **Note:** Also available at `/chromium/unblock` as a convenience alias.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: >-
              Restrict blockAds to a specific set of uBlock ruleset ids
              (comma-separated

              list or JSON array). Only applies when `blockAds` is true. Fewer
              rulesets

              means a faster browser launch under load; omit to load the full
              default set.
            type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: replay
          schema:
            description: >-
              When true, records the unblock session for replay (rrweb) and
              uploads the

              captured replay on cleanup, reusing the same recording pipeline as

              BrowserQL. Like every other Browserless route, replay is a

              connection-level flag supplied via this `?replay=true` query
              parameter

              (the browser's recording config is resolved from the URL at
              launch).

              Defaults to false.
            type: boolean
        - in: query
          name: solveCaptchas
          schema:
            description: >-
              When `browserWSEndpoint` is requested, persists captcha-solving on
              the

              kept-alive session so reconnections automatically solve captchas
              without

              having to re-add `?solveCaptchas=true` to the returned reconnect
              URL.

              Connection-level flag supplied via this `?solveCaptchas=true`
              query

              parameter, mirroring `replay`. Defaults to false.
            type: boolean
        - 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:
          application/json:
            schema:
              properties:
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless will attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                url:
                  description: The URL of the site you want to unblock.
                  type: string
                browserWSEndpoint:
                  description: >-
                    Whether or not to keep the underlying browser alive and
                    around for

                    future reconnects. Defaults to false.
                  type: boolean
                cookies:
                  description: >-
                    Whether or not to to return cookies for the site, defaults
                    to true.
                  type: boolean
                content:
                  description: >-
                    Whether or not to to return content for the site, defaults
                    to true.
                  type: boolean
                screenshot:
                  description: >-
                    Whether or not to to return a full-page screenshot for the
                    site, defaults to true.
                  type: boolean
                ttl:
                  description: |-
                    When the browserWSEndpoint is requested this tells
                    browserless how long to keep this browser alive for
                    re-connection until shutting it down completely.
                    Maximum of 30000 for 30 seconds (30,000ms).
                  type: number
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    An optional goto parameter object for considering when the
                    page is done loading.
                waitForEvent:
                  description: >-
                    Options for waiting for a specific event to be fired on the
                    page.
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  description: Options for waiting for a JavaScript function to execute.
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  description: >-
                    Options for waiting for a specific CSS selector to appear on
                    the page.
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  description: >-
                    The amount of time in milliseconds to wait before
                    proceeding.
                  type: number
              type: object
              required:
                - url
              example: *ref_0
            example:
              bestAttempt: true
              url: string
              browserWSEndpoint: true
              cookies: true
              content: true
              screenshot: true
              ttl: 0
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  cookies:
                    description: >-
                      A list of cookies which can be used for new connections or
                      for usage elsewhere.

                      Value is "null" when the request body specifies cookies:
                      false.
                    type: array
                    items:
                      $ref: '#/components/schemas/UnblockCookie'
                  content:
                    description: >-
                      The HTML content of the page once it is passed bot
                      detection.

                      Value is "null" when the request body specifies content:
                      false.
                    type: string
                  browserWSEndpoint:
                    description: >-
                      The browserWSEndpoint of the response when the POST body
                      contains a

                      browserWSEndpoint: true property
                    type: string
                  ttl:
                    description: >-
                      The time the browser will remain alive until it is
                      shutdown. Zero

                      when browserWSEndpoint: false is set in the request
                      payload. The limit

                      is 60000 or 60 seconds, which is the maximum allowed time.
                    type: number
                  screenshot:
                    description: A base64 encoded JPEG of the of the final site page.
                    type: string
                additionalProperties: false
                required:
                  - browserWSEndpoint
                  - content
                  - cookies
                  - screenshot
                  - ttl
                definitions:
                  UnblockCookie:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                      domain:
                        type: string
                      path:
                        type: string
                      expires:
                        type: number
                      httpOnly:
                        type: boolean
                      secure:
                        type: boolean
                      sameSite:
                        type: string
                      url:
                        type: string
                    additionalProperties: false
                    required:
                      - domain
                      - expires
                      - httpOnly
                      - name
                      - path
                      - sameSite
                      - secure
                      - url
                      - value
                $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: /unblock
      tags:
        - Unblock & Stealth
  /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: 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
  /profile:
    post:
      description: >-
        Launches a temporary browser session for creating an authenticated
        profile.

        Connect via the returned WebSocket URL, authenticate in the browser,

        then call Browserless.saveProfile via CDP to capture and persist the
        auth state.

        The profile is NOT saved automatically — you must explicitly call

        Browserless.saveProfile before disconnecting. The session expires after
        10 minutes.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  description: |-
                    A user-visible name for the profile.
                    Must be unique per token.
                  type: string
                stealth:
                  description: >-
                    Whether or not to enable advanced stealth mode. Defaults to
                    false.
                  type: boolean
                browser:
                  description: The type of browser to use. Defaults to 'stealth'.
                  enum:
                    - chrome
                    - chromium
                    - stealth
                  type: string
                args:
                  description: An array of command-line arguments to pass to the browser.
                  type: array
                  items:
                    type: string
                proxy:
                  description: Proxy parameters for the profile creation session.
                  type: object
                  properties:
                    type:
                      description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
                      enum:
                        - datacenter
                        - residential
                      type: string
                    sticky:
                      description: >-
                        Whether or not to use the same IP address for all
                        proxied requests. Defaults to true.
                      type: boolean
                    country:
                      description: >-
                        The country to proxy through. Defaults to 'us' or United
                        States.
                      type: string
                    city:
                      description: The city to proxy through.
                      type: string
                    state:
                      description: The state to proxy through.
                      type: string
                    preset:
                      description: >-
                        Preset code for website-specific proxy configurations
                        (e.g., 'px_gov01' for government sites).
                      type: string
                  additionalProperties: false
                integrationId:
                  description: >-
                    Optional 1Password integration id. When set, the
                    profile-authoring session

                    can fill credentials via Browserless.loadSecret.
                  type: string
                credentials:
                  description: >-
                    Optional alias → op:// reference map for the integration
                    above.
                  type: object
                  additionalProperties:
                    type: string
                allowedDomains:
                  description: >-
                    Optional per-session narrowing of the integration's allowed
                    domains.
                  type: array
                  items:
                    type: string
              type: object
              required:
                - name
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: Temporary session ID used for the profile creation browser
                    type: string
                  name:
                    description: The profile name that will be used when saving
                    type: string
                  connect:
                    description: WebSocket URL to connect to the browser
                    type: string
                  stop:
                    description: URL to stop/delete the temporary session
                    type: string
                additionalProperties: false
                required:
                  - connect
                  - id
                  - name
                  - stop
                $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: /profile
      tags:
        - Profiles
      operationId: profile-create
  /profiles:
    get:
      description: >-
        Lists authentication profiles owned by the requesting token.

        Paginated via "limit" (default 100, capped at 1000) and "offset"
        (default 0).

        Returns an empty array if the token has no profiles.
      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: 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: limit
          schema:
            description: Maximum number of profiles to return (1–1000). Defaults to 100.
            type: number
        - in: query
          name: offset
          schema:
            description: Number of profiles to skip for pagination. Defaults to 0.
            type: number
        - 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: array
                items:
                  $ref: '#/components/schemas/ProfileResponse'
                definitions:
                  ProfileResponse:
                    description: |-
                      Public-facing profile response returned by HTTP routes.
                      Omits internal fields like token_hash and storage_key.
                    type: object
                    properties:
                      id:
                        description: Unique profile identifier.
                        type: string
                      name:
                        description: User-supplied profile name. Unique per token.
                        type: string
                      cookieCount:
                        description: Number of cookies captured in the profile.
                        type: number
                      originCount:
                        description: >-
                          Number of distinct origins with stored localStorage or
                          IndexedDB.
                        type: number
                      lastUsedAt:
                        description: >-
                          ISO timestamp of the last time this profile was
                          applied to a session, or null if never used.
                        type: string
                      createdAt:
                        description: ISO timestamp of when the profile was created.
                        type: string
                      updatedAt:
                        description: >-
                          ISO timestamp of the last metadata change (e.g.,
                          rename).
                        type: string
                    additionalProperties: false
                    required:
                      - cookieCount
                      - createdAt
                      - id
                      - lastUsedAt
                      - name
                      - originCount
                      - updatedAt
                $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: /profiles
      tags:
        - Profiles
  /profile/*:
    delete:
      description: |-
        Deletes an authentication profile and its captured state.
        The profile name is the URL-encoded path segment after "/profile/".
        Returns 404 if no profile with that name exists for this token.
      parameters: []
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    description: Always true on success.
                    type: boolean
                  message:
                    description: Human-readable confirmation message.
                    type: string
                  name:
                    description: Name of the profile that was deleted.
                    type: string
                additionalProperties: false
                required:
                  - message
                  - name
                  - success
                $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: /profile/*
      tags:
        - Profiles
      operationId: profile-delete
    get:
      description: |-
        Returns metadata for a specific authentication profile.
        The profile name is the URL-encoded path segment after "/profile/".
        Returns 404 if no profile with that name exists for this token.
      parameters: []
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: Unique profile identifier.
                    type: string
                  name:
                    description: User-supplied profile name. Unique per token.
                    type: string
                  cookieCount:
                    description: Number of cookies captured in the profile.
                    type: number
                  originCount:
                    description: >-
                      Number of distinct origins with stored localStorage or
                      IndexedDB.
                    type: number
                  lastUsedAt:
                    description: >-
                      ISO timestamp of the last time this profile was applied to
                      a session, or null if never used.
                    type: string
                  createdAt:
                    description: ISO timestamp of when the profile was created.
                    type: string
                  updatedAt:
                    description: ISO timestamp of the last metadata change (e.g., rename).
                    type: string
                additionalProperties: false
                required:
                  - cookieCount
                  - createdAt
                  - id
                  - lastUsedAt
                  - name
                  - originCount
                  - updatedAt
                $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: /profile/*
      tags:
        - Profiles
      operationId: profile-get
    put:
      description: >-
        Renames an authentication profile. The new name must be unique per
        token.

        The current name is the URL-encoded path segment after "/profile/".

        Returns 400 if the new name is already taken, 404 if the source profile
        is not found.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  description: The new name for the profile.
                  type: string
              type: object
              required:
                - name
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: Unique profile identifier.
                    type: string
                  name:
                    description: User-supplied profile name. Unique per token.
                    type: string
                  cookieCount:
                    description: Number of cookies captured in the profile.
                    type: number
                  originCount:
                    description: >-
                      Number of distinct origins with stored localStorage or
                      IndexedDB.
                    type: number
                  lastUsedAt:
                    description: >-
                      ISO timestamp of the last time this profile was applied to
                      a session, or null if never used.
                    type: string
                  createdAt:
                    description: ISO timestamp of when the profile was created.
                    type: string
                  updatedAt:
                    description: ISO timestamp of the last metadata change (e.g., rename).
                    type: string
                additionalProperties: false
                required:
                  - cookieCount
                  - createdAt
                  - id
                  - lastUsedAt
                  - name
                  - originCount
                  - updatedAt
                $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: /profile/*
      tags:
        - Profiles
      operationId: profile-rename
  /profile/refresh:
    post:
      description: |-
        Replaces the state of an existing authentication profile in place.
        The "name" must already exist for the requesting token. Counts of any
        dropped or truncated entries are surfaced under "diagnostics".
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  description: >-
                    Name of the existing profile to refresh. Must already exist
                    for the

                    requesting token.
                  type: string
                state:
                  description: >-
                    Pre-captured authentication state. Same shape as `POST
                    /profile/upload`.
              type: object
              required:
                - name
                - state
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  diagnostics:
                    $ref: '#/components/schemas/RefreshResponseDiagnostics'
                    description: >-
                      Per-entry counts of cookies, origins, and IndexedDB items
                      the server

                      dropped or truncated before persisting. All zero on a
                      clean refresh.
                  id:
                    description: Unique profile identifier.
                    type: string
                  name:
                    description: User-supplied profile name. Unique per token.
                    type: string
                  cookieCount:
                    description: Number of cookies captured in the profile.
                    type: number
                  originCount:
                    description: >-
                      Number of distinct origins with stored localStorage or
                      IndexedDB.
                    type: number
                  lastUsedAt:
                    description: >-
                      ISO timestamp of the last time this profile was applied to
                      a session, or null if never used.
                    type: string
                  createdAt:
                    description: ISO timestamp of when the profile was created.
                    type: string
                  updatedAt:
                    description: ISO timestamp of the last metadata change (e.g., rename).
                    type: string
                additionalProperties: false
                required:
                  - cookieCount
                  - createdAt
                  - diagnostics
                  - id
                  - lastUsedAt
                  - name
                  - originCount
                  - updatedAt
                definitions:
                  RefreshResponseDiagnostics:
                    description: >-
                      Per-entry counts of cookies, origins, and IndexedDB items
                      the server

                      dropped or truncated before persisting. All zero on a
                      clean refresh.
                    type: object
                    properties:
                      skippedMalformedCookies:
                        description: >-
                          Cookies dropped because required fields were missing
                          or wrong type.
                        type: number
                      skippedPrivateCookies:
                        description: >-
                          Cookies dropped because their domain pointed at a
                          private/internal host.
                        type: number
                      skippedMalformedOrigins:
                        description: >-
                          Origins dropped because they were malformed or
                          non-http(s).
                        type: number
                      skippedPrivateOrigins:
                        description: >-
                          Origins dropped because they targeted a
                          private/internal network.
                        type: number
                      truncatedOrigins:
                        description: >-
                          Origins dropped because the per-profile cap was
                          exceeded.
                        type: number
                      skippedMalformedIdbDatabases:
                        description: >-
                          IndexedDB databases dropped because required fields
                          were missing.
                        type: number
                      truncatedIdbDatabases:
                        description: >-
                          IndexedDB databases dropped because the per-origin cap
                          was exceeded.
                        type: number
                      skippedMalformedIdbStores:
                        description: >-
                          IndexedDB object-stores dropped because required
                          fields were missing.
                        type: number
                      truncatedIdbEntries:
                        description: >-
                          IndexedDB entries dropped because the per-store cap
                          was exceeded.
                        type: number
                    additionalProperties: false
                    required:
                      - skippedMalformedCookies
                      - skippedMalformedIdbDatabases
                      - skippedMalformedIdbStores
                      - skippedMalformedOrigins
                      - skippedPrivateCookies
                      - skippedPrivateOrigins
                      - truncatedIdbDatabases
                      - truncatedIdbEntries
                      - truncatedOrigins
                $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: /profile/refresh
      tags:
        - Profiles
  /profile/upload:
    post:
      description: |-
        Creates a new authentication profile from a pre-captured "state" payload
        (cookies plus per-origin localStorage and IndexedDB). The "name" must be
        unique per token. Counts of any dropped or truncated entries are
        surfaced under "diagnostics".
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  description: >-
                    A user-visible name for the profile. Must be unique per
                    token.
                  type: string
                state:
                  description: >-
                    Pre-captured authentication state. An object with two arrays
                    —

                    `cookies` (browser cookies) and `origins` (per-origin
                    localStorage and

                    IndexedDB).
              type: object
              required:
                - name
                - state
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  diagnostics:
                    $ref: '#/components/schemas/UploadResponseDiagnostics'
                    description: >-
                      Per-entry counts of cookies, origins, and IndexedDB items
                      the server

                      dropped or truncated before persisting. All zero on a
                      clean upload.
                  id:
                    description: Unique profile identifier.
                    type: string
                  name:
                    description: User-supplied profile name. Unique per token.
                    type: string
                  cookieCount:
                    description: Number of cookies captured in the profile.
                    type: number
                  originCount:
                    description: >-
                      Number of distinct origins with stored localStorage or
                      IndexedDB.
                    type: number
                  lastUsedAt:
                    description: >-
                      ISO timestamp of the last time this profile was applied to
                      a session, or null if never used.
                    type: string
                  createdAt:
                    description: ISO timestamp of when the profile was created.
                    type: string
                  updatedAt:
                    description: ISO timestamp of the last metadata change (e.g., rename).
                    type: string
                additionalProperties: false
                required:
                  - cookieCount
                  - createdAt
                  - diagnostics
                  - id
                  - lastUsedAt
                  - name
                  - originCount
                  - updatedAt
                definitions:
                  UploadResponseDiagnostics:
                    description: >-
                      Per-entry counts of cookies, origins, and IndexedDB items
                      the server

                      dropped or truncated before persisting. All zero on a
                      clean upload.
                    type: object
                    properties:
                      skippedMalformedCookies:
                        description: >-
                          Cookies dropped because required fields were missing
                          or wrong type.
                        type: number
                      skippedPrivateCookies:
                        description: >-
                          Cookies dropped because their domain pointed at a
                          private/internal host.
                        type: number
                      skippedMalformedOrigins:
                        description: >-
                          Origins dropped because they were malformed or
                          non-http(s).
                        type: number
                      skippedPrivateOrigins:
                        description: >-
                          Origins dropped because they targeted a
                          private/internal network.
                        type: number
                      truncatedOrigins:
                        description: >-
                          Origins dropped because the per-profile cap was
                          exceeded.
                        type: number
                      skippedMalformedIdbDatabases:
                        description: >-
                          IndexedDB databases dropped because required fields
                          were missing.
                        type: number
                      truncatedIdbDatabases:
                        description: >-
                          IndexedDB databases dropped because the per-origin cap
                          was exceeded.
                        type: number
                      skippedMalformedIdbStores:
                        description: >-
                          IndexedDB object-stores dropped because required
                          fields were missing.
                        type: number
                      truncatedIdbEntries:
                        description: >-
                          IndexedDB entries dropped because the per-store cap
                          was exceeded.
                        type: number
                    additionalProperties: false
                    required:
                      - skippedMalformedCookies
                      - skippedMalformedIdbDatabases
                      - skippedMalformedIdbStores
                      - skippedMalformedOrigins
                      - skippedPrivateCookies
                      - skippedPrivateOrigins
                      - truncatedIdbDatabases
                      - truncatedIdbEntries
                      - truncatedOrigins
                $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: /profile/upload
      tags:
        - Profiles
  /integrations/onepassword:
    post:
      description: >-
        Registers a 1Password integration for the requesting token. The supplied

        service-account token is encrypted at rest and is never returned by this
        or

        any other endpoint. Returns the created integration without any token
        field.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                label:
                  description: A user-visible label for the integration. Unique per token.
                  type: string
                kind:
                  description: Integration kind. Defaults to "service_account".
                  enum:
                    - connect
                    - service_account
                  type: string
                serviceAccountToken:
                  description: >-
                    The 1Password service-account token (or Connect access token
                    when

                    kind is "connect"). Encrypted at rest; never returned by any
                    API.
                  type: string
                allowedDomains:
                  description: >-
                    Origins this integration may fill credentials into. Empty
                    means no fills pass.
                  type: array
                  items:
                    type: string
                connectUrl:
                  description: >-
                    Connect server URL. Required when kind is "connect",
                    rejected otherwise.
                  type: string
              type: object
              required:
                - label
                - serviceAccountToken
      responses:
        '200':
          content:
            application/json:
              schema:
                description: >-
                  Public-facing integration response returned by HTTP routes.

                  Omits internal fields — never includes token_hash or any token
                  material.
                type: object
                properties:
                  id:
                    description: Unique integration identifier.
                    type: string
                  label:
                    description: User-supplied label. Unique per token.
                    type: string
                  kind:
                    $ref: '#/components/schemas/OpIntegrationKind'
                    description: >-
                      Integration kind: `service_account` (default) or
                      `connect`.
                  allowedDomains:
                    description: Origins this integration is allowed to fill into.
                    type: array
                    items:
                      type: string
                  connectUrl:
                    description: Connect server URL when kind is `connect`, otherwise null.
                    type: string
                  expiresAt:
                    description: >-
                      ISO timestamp after which the integration is treated as
                      expired, or null.
                    type: string
                  lastResolvedAt:
                    description: >-
                      ISO timestamp of the last successful secret resolve, or
                      null if never used.
                    type: string
                  createdAt:
                    description: ISO timestamp of when the integration was created.
                    type: string
                  updatedAt:
                    description: ISO timestamp of the last metadata change.
                    type: string
                additionalProperties: false
                required:
                  - allowedDomains
                  - connectUrl
                  - createdAt
                  - expiresAt
                  - id
                  - kind
                  - label
                  - lastResolvedAt
                  - updatedAt
                definitions:
                  OpIntegrationKind:
                    enum:
                      - connect
                      - service_account
                    type: string
                $schema: http://json-schema.org/draft-07/schema#
          description: >-
            Public-facing integration response returned by HTTP routes.

            Omits internal fields — never includes token_hash or any token
            material.
        '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: /integrations/onepassword
      tags:
        - Integrations
      operationId: onepassword-register
    get:
      description: >-
        Lists the 1Password integrations owned by the requesting token.
        Paginated

        via "limit" (default 100, capped at 1000) and "offset" (default 0).
        Records

        never include any token material.
      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: 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: limit
          schema:
            description: >-
              Maximum number of integrations to return (1–1000). Defaults to
              100.
            type: number
        - in: query
          name: offset
          schema:
            description: Number of integrations to skip for pagination. Defaults to 0.
            type: number
        - 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: array
                items:
                  $ref: '#/components/schemas/OpIntegrationResponse'
                definitions:
                  OpIntegrationResponse:
                    description: >-
                      Public-facing integration response returned by HTTP
                      routes.

                      Omits internal fields — never includes token_hash or any
                      token material.
                    type: object
                    properties:
                      id:
                        description: Unique integration identifier.
                        type: string
                      label:
                        description: User-supplied label. Unique per token.
                        type: string
                      kind:
                        $ref: '#/components/schemas/OpIntegrationKind'
                        description: >-
                          Integration kind: `service_account` (default) or
                          `connect`.
                      allowedDomains:
                        description: Origins this integration is allowed to fill into.
                        type: array
                        items:
                          type: string
                      connectUrl:
                        description: >-
                          Connect server URL when kind is `connect`, otherwise
                          null.
                        type: string
                      expiresAt:
                        description: >-
                          ISO timestamp after which the integration is treated
                          as expired, or null.
                        type: string
                      lastResolvedAt:
                        description: >-
                          ISO timestamp of the last successful secret resolve,
                          or null if never used.
                        type: string
                      createdAt:
                        description: ISO timestamp of when the integration was created.
                        type: string
                      updatedAt:
                        description: ISO timestamp of the last metadata change.
                        type: string
                    additionalProperties: false
                    required:
                      - allowedDomains
                      - connectUrl
                      - createdAt
                      - expiresAt
                      - id
                      - kind
                      - label
                      - lastResolvedAt
                      - updatedAt
                  OpIntegrationKind:
                    enum:
                      - connect
                      - service_account
                    type: string
                $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: /integrations/onepassword
      tags:
        - Integrations
      operationId: onepassword-list
  /integrations/onepassword/*:
    delete:
      description: >-
        Deletes a 1Password integration owned by the requesting token. The id is
        the

        URL-encoded path segment after "/integrations/onepassword/". Returns 404
        if

        no integration with that id exists for this token. Deleting an
        integration

        does not touch any authentication profile.
      parameters: []
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    description: Always true on success.
                    type: boolean
                  message:
                    description: Human-readable confirmation message.
                    type: string
                  id:
                    description: Id of the integration that was deleted.
                    type: string
                additionalProperties: false
                required:
                  - id
                  - message
                  - success
                $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: /integrations/onepassword/*
      tags:
        - Integrations
      operationId: onepassword-delete
    get:
      description: >-
        Returns metadata for a specific 1Password integration owned by the
        token.

        The id is the URL-encoded path segment after
        "/integrations/onepassword/".

        Returns 404 if no integration with that id exists for this token. The

        response never includes any token material.
      parameters: []
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: Unique integration identifier.
                    type: string
                  label:
                    description: User-supplied label. Unique per token.
                    type: string
                  kind:
                    $ref: '#/components/schemas/OpIntegrationKind'
                    description: >-
                      Integration kind: `service_account` (default) or
                      `connect`.
                  allowedDomains:
                    description: Origins this integration is allowed to fill into.
                    type: array
                    items:
                      type: string
                  connectUrl:
                    description: Connect server URL when kind is `connect`, otherwise null.
                    type: string
                  expiresAt:
                    description: >-
                      ISO timestamp after which the integration is treated as
                      expired, or null.
                    type: string
                  lastResolvedAt:
                    description: >-
                      ISO timestamp of the last successful secret resolve, or
                      null if never used.
                    type: string
                  createdAt:
                    description: ISO timestamp of when the integration was created.
                    type: string
                  updatedAt:
                    description: ISO timestamp of the last metadata change.
                    type: string
                additionalProperties: false
                required:
                  - allowedDomains
                  - connectUrl
                  - createdAt
                  - expiresAt
                  - id
                  - kind
                  - label
                  - lastResolvedAt
                  - updatedAt
                definitions:
                  OpIntegrationKind:
                    enum:
                      - connect
                      - service_account
                    type: string
                $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: /integrations/onepassword/*
      tags:
        - Integrations
      operationId: onepassword-get
  /integrations/onepassword/*/audit:
    get:
      description: >-
        Lists recent credential-fill activity for a single 1Password integration

        owned by the token, newest first. One entry per Browserless.loadSecret

        attempt: outcome, error code, the credential reference, and non-secret

        target metadata. A resolved secret value is never recorded or returned.

        Paginated via "limit" (default 100, capped at 1000) and "offset"
        (default 0).

        Returns 404 if no integration with that id exists for this token.
      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: 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: limit
          schema:
            description: >-
              Maximum number of audit entries to return (1–1000). Defaults to
              100.
            type: number
        - in: query
          name: offset
          schema:
            description: Number of audit entries to skip for pagination. Defaults to 0.
            type: number
        - 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: array
                items:
                  $ref: '#/components/schemas/OpAuditLogResponse'
                definitions:
                  OpAuditLogResponse:
                    description: >-
                      Public-facing audit-log entry returned by the audit HTTP
                      route. Omits

                      token_hash — never includes any token material — and
                      carries the credential

                      reference plus non-secret target metadata only.
                    type: object
                    properties:
                      id:
                        description: Unique audit-entry identifier.
                        type: string
                      integrationId:
                        description: Integration this fill attempt was made through.
                        type: string
                      profileId:
                        description: Authentication profile the fill targeted, or null.
                        type: string
                      secretRef:
                        description: >-
                          The alias or op:// reference requested. Never a
                          resolved value.
                        type: string
                      targetOrigin:
                        description: Document origin the fill was attempted on, or null.
                        type: string
                      targetSelector:
                        description: CSS selector supplied by the caller, or null.
                        type: string
                      targetDescriptor:
                        description: Non-secret descriptor of the focused element, or null.
                        type: string
                      outcome:
                        $ref: '#/components/schemas/OpAuditOutcome'
                        description: >-
                          `success` if the value was filled, otherwise
                          `failure`.
                      errorCode:
                        description: >-
                          Error code when the outcome is `failure`, otherwise
                          null.
                        type: string
                      createdAt:
                        description: ISO timestamp of the attempt.
                        type: string
                    additionalProperties: false
                    required:
                      - createdAt
                      - errorCode
                      - id
                      - integrationId
                      - outcome
                      - profileId
                      - secretRef
                      - targetDescriptor
                      - targetOrigin
                      - targetSelector
                  OpAuditOutcome:
                    description: >-
                      Outcome recorded for a single Browserless.loadSecret
                      attempt.
                    enum:
                      - failure
                      - success
                    type: string
                $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: /integrations/onepassword/*/audit
      tags:
        - Integrations
  /integrations/onepassword/profile:
    post:
      description: >-
        Kicks off an autologin task: a managed agent creates a browser profile
        by

        logging into the integration's domains, then saves it. Returns a taskId
        to

        poll via GET /integrations/onepassword/profile/:taskId. (POC: the
        integration

        is resolved from an in-memory fixture rather than a real 1Password
        record.)
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  description: Name to save the resulting profile under. Unique per token.
                  type: string
                integrationId:
                  description: >-
                    Integration id — resolved from the in-memory fixture in this
                    POC.
                  type: string
                allowedDomains:
                  description: Optional subset of the integration's allowed domains.
                  type: array
                  items:
                    type: string
              type: object
              required:
                - integrationId
                - name
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskId:
                    type: string
                additionalProperties: false
                required:
                  - taskId
                $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: /integrations/onepassword/profile
      tags:
        - Integrations
      operationId: onepassword-autologin-start
  /integrations/onepassword/profile/*:
    get:
      description: >-
        Poll an autologin task by id. Returns its state, the current live
        rationale,

        and (on success) the saved profile id plus a per-domain breakdown.
        Scoped to

        the requesting token — returns 404 for unknown ids or another token's
        task.
      parameters: []
      requestBody:
        content: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                description: >-
                  Public polling shape returned by GET
                  /integrations/onepassword/profile/:taskId.
                type: object
                properties:
                  taskId:
                    type: string
                  state:
                    $ref: '#/components/schemas/AutologinState'
                  currentRationale:
                    description: >-
                      User-facing reason for the current state — drives the
                      dashboard's live line.
                    type: string
                  profileId:
                    type: string
                  profileName:
                    type: string
                  domains:
                    type: array
                    items:
                      $ref: '#/components/schemas/AutologinDomainResult'
                  errorCode:
                    type: string
                  errorMessage:
                    type: string
                  createdAt:
                    type: string
                  updatedAt:
                    type: string
                additionalProperties: false
                required:
                  - createdAt
                  - currentRationale
                  - state
                  - taskId
                  - updatedAt
                definitions:
                  AutologinState:
                    description: Lifecycle state of an autologin task.
                    enum:
                      - failed
                      - pending
                      - running
                      - success
                    type: string
                  AutologinDomainResult:
                    type: object
                    properties:
                      origin:
                        type: string
                      status:
                        $ref: '#/components/schemas/AutologinDomainStatus'
                      error:
                        type: string
                    additionalProperties: false
                    required:
                      - origin
                      - status
                  AutologinDomainStatus:
                    description: >-
                      Per-origin progress/outcome as the agent works through the
                      domain list.

                      Live: `pending` (not reached), `active` (currently
                      attempting), `tried`

                      (moved past — outcome not yet known). Terminal: `success`
                      | `failed`.
                    enum:
                      - active
                      - failed
                      - pending
                      - success
                      - tried
                    type: string
                $schema: http://json-schema.org/draft-07/schema#
          description: >-
            Public polling shape returned by GET
            /integrations/onepassword/profile/:taskId.
        '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: /integrations/onepassword/profile/*
      tags:
        - Integrations
      operationId: onepassword-autologin-status
  /integrations/onepassword/autologin/form:
    get:
      description: >-
        Returns the selectable references for building an autologin profile: the

        1Password integration's login origins and, per origin, the field labels
        it

        fills (never values). Drives the create-profile form.
      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: integrationId
          schema:
            description: Which registered 1Password integration's login items to return.
            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:
                  integrationId:
                    type: string
                  domains:
                    type: array
                    items:
                      type: object
                      properties:
                        origin:
                          type: string
                        credentialTypes:
                          type: array
                          items:
                            type: string
                      additionalProperties: false
                      required:
                        - credentialTypes
                        - origin
                additionalProperties: false
                required:
                  - domains
                  - integrationId
                $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: /integrations/onepassword/autologin/form
      tags:
        - Integrations
  /:
    get:
      description: >-
        Launch and connect to Chromium with a library like puppeteer or others
        that work over chrome-devtools-protocol.


        **Note:** Also available at `/chromium` as a convenience alias.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: integrations
          schema:
            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'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: record
          schema:
            type: boolean
        - in: query
          name: replay
          schema:
            type: boolean
        - in: query
          name: solveCaptchas
          schema:
            type: boolean
        - 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:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /
      tags:
        - WebSocket APIs
      operationId: chromium-root
  /chromium:
    get:
      description: >-
        Launch and connect to Chromium with a library like puppeteer or others
        that work over chrome-devtools-protocol.


        **Note:** This endpoint is also available at: `/` for backwards
        compatibility.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chromium
      tags:
        - WebSocket APIs
  /chromium/playwright:
    get:
      description: |-
        Connect to Chromium with any playwright style library.

        **Note:** Also available at `/playwright` as a convenience alias.
      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: 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/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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chromium/playwright
      tags:
        - WebSocket APIs
  /edge:
    get:
      description: >-
        Launch and connect to Chromium with a library like puppeteer or others
        that work over chrome-devtools-protocol.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: integrations
          schema:
            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'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: record
          schema:
            type: boolean
        - in: query
          name: replay
          schema:
            type: boolean
        - in: query
          name: solveCaptchas
          schema:
            type: boolean
        - 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:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /edge
      tags:
        - WebSocket APIs
  /edge/playwright:
    get:
      description: Connect to Chromium with any playwright style library.
      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: 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/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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /edge/playwright
      tags:
        - WebSocket APIs
  /firefox/playwright:
    get:
      description: >-
        Connect to Firefox with any playwright-compliant library.


        **Note:** Also available at `/playwright/firefox` as a convenience
        alias.
      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: 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.
            additionalProperties: false
            type: object
            properties:
              args:
                type: array
                items:
                  type: string
              chromiumSandbox:
                type: boolean
              devtools:
                type: boolean
              downloadsPath:
                type: string
              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
              firefoxUserPrefs:
                type: object
                additionalProperties:
                  type:
                    - string
                    - number
                    - boolean
        - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /firefox/playwright
      tags:
        - WebSocket APIs
  /webkit/playwright:
    get:
      description: |-
        Connect to Webkit with any playwright-compliant library.

        **Note:** Also available at `/playwright/webkit` as a convenience alias.
      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: 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/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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /webkit/playwright
      tags:
        - WebSocket APIs
  /live/*:
    get:
      description: >-
        > This API is only available on paid plans. [Sign-up
        here](https://www.browserless.io/pricing/).


        Websocket back-end that powers the live session experience.


        **Note:** Also available at `/chromium/live/*` as a convenience alias.
      parameters: []
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /live/*
      tags:
        - WebSocket APIs
  /session/bql/*:
    post:
      description: >-
        > Executes BrowserQL queries against an existing session. The session
        must be a stealth session to support BrowserQL.


        BrowserQL is a GraphQL-based query language for browser automation that
        allows you to interact with web pages using a declarative syntax.

        Queries execute within the context of your existing session, maintaining
        browser state and session data across multiple operations.
      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: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.

              Must be either JSON object, or a base64-encoded JSON object.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: replay
          schema:
            type: boolean
        - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                query:
                  description: >-
                    The GraphQL query string to execute against the browser
                    session.


                    Example queries:

                    - Get browser info: `query { version browser }`

                    - Navigate and get content: `mutation { goto(url:
                    "https://example.com") { status } title { title } url { url
                    } }`

                    - Fill form and submit: `mutation { goto(url:
                    "https://example.com") { status } type(selector:
                    "input[name='email']", text: "user@example.com") { time }
                    click(selector: "button[type='submit']") { time } }`

                    - Extract data: `mutation { querySelector(selector: "h1") {
                    innerHTML } querySelectorAll(selector: ".product") {
                    innerHTML className } }`
                  type: string
                variables:
                  description: >-
                    Variables to pass to the GraphQL query. Useful for dynamic
                    values.


                    Example: `{ "url": "https://example.com", "selector": "h1",
                    "text": "Hello World" }`
                  type: object
                  additionalProperties: {}
                operationName:
                  description: >-
                    The name of the operation to execute if the query contains
                    multiple operations.

                    Optional - only needed when query has multiple named
                    operations.
                  type: string
              type: object
              required:
                - query
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AnyRecord'
                    description: >-
                      The GraphQL response data. Contains the result of the
                      executed query.

                      Structure depends on the specific query executed.


                      Example responses:

                      - Navigation + Title + Element: `{ "goto": { "status": 200
                      }, "title": { "title": "Example Domain" },
                      "querySelector": { "innerHTML": "Example Domain" } }`

                      - Multiple elements: `{ "querySelectorAll": [{
                      "innerHTML": "Item 1" }, { "innerHTML": "Item 2" }] }`

                      - Screenshot: `{ "screenshot": { "data":
                      "base64encodedimage", "type": "png" } }`

                      - PDF: `{ "pdf": { "data": "base64encodedpdf" } }`

                      - System info: `{ "version": "1.0.0", "browser":
                      "Chrome/120.0.0.0" }`

                      - Form interaction: `{ "type": { "success": true },
                      "click": { "success": true } }`
                  errors:
                    description: >-
                      Array of GraphQL errors, if any occurred during query
                      execution.

                      Only present when errors exist.
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          description: Error message describing what went wrong
                          type: string
                        locations:
                          description: Locations in the query where the error occurred
                          type: array
                          items:
                            type: object
                            properties:
                              line:
                                type: number
                              column:
                                type: number
                            additionalProperties: false
                            required:
                              - column
                              - line
                        path:
                          description: Path to the field that caused the error
                          type: array
                          items:
                            type:
                              - string
                              - number
                      additionalProperties: false
                      required:
                        - message
                additionalProperties: false
                definitions:
                  Record<string,any>:
                    type: object
                    additionalProperties: false
                $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: /session/bql/*
      tags:
        - Sessions & Connections
  /reconnect/*:
    get:
      description: >-
        Reconnect to an existing Chromium or Chrome session with a library like
        puppeteer or others that work over chrome-devtools-protocol.
      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: integrations
          schema:
            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: replay
          schema:
            type: boolean
        - in: query
          name: solveCaptchas
          schema:
            type: boolean
        - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /reconnect/*
      tags:
        - Sessions & Connections
  /session/connect/*:
    get:
      description: >-
        Connect to an existing session with a library like puppeteer or
        playwright that work over chrome-devtools-protocol. See documentation
        for more details on how to start the session.


        The browser type (Chrome/Chromium, stealth/regular) is determined from
        the session metadata when it was created initially.
      parameters:
        - in: query
          name: launch
          schema:
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - type: string
        - in: query
          name: replay
          schema:
            type: boolean
        - in: query
          name: timeout
          schema:
            type: number
        - in: query
          name: token
          schema:
            type: string
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /session/connect/*
      tags:
        - Sessions & Connections
  /chrome/screenshot:
    post:
      description: >-
        Returns a screenshot binary from a `url` or `html` payload (Chrome,
        legacy).

        "url" or "html" payload in your request. Many options exist including

        cookies, user-agents, setting timers and network mocks.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                addScriptTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  anyOf:
                    - $ref: '#/components/schemas/Credentials'
                    - type: 'null'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                emulateMediaType:
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  type: string
                options:
                  $ref: '#/components/schemas/ScreenshotOptions'
                  description: >-
                    Screenshot options based on Puppeteer's ScreenshotOptions
                    interface.

                    Includes properties like `type`, `quality`, `fullPage`,
                    `clip`, etc.
                rejectRequestPattern:
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                            $ref: '#/components/schemas/AnyRecord'
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                scrollPage:
                  type: boolean
                selector:
                  type: string
                setExtraHTTPHeaders:
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  type: boolean
                url:
                  type: string
                userAgent:
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      description: >-
                        Used to specify User Agent Client Hints to emulate. See
                        https://wicg.github.io/ua-client-hints

                        Missing optional values will be filled in by the target
                        with what it would normally use.
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  anyOf:
                    - $ref: '#/components/schemas/Viewport'
                    - type: 'null'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  type: number
              type: object
              example: *ref_0
            example:
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              options:
                optimizeForSpeed: true
                type: jpeg
                quality: 0
                fromSurface: true
                fullPage: true
                omitBackground: true
                clip:
                  scale: 0
                  width: 0
                  height: 0
                  x: 0
                  'y': 0
                encoding: base64
                captureBeyondViewport: true
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              scrollPage: true
              selector: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
                format: byte
          description: |-
            Response can either be a text/plain base64 encoded body
            or a binary stream with png/jpeg as a content-type
        '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: /chrome/screenshot
      tags:
        - Chrome (licensed build)
  /chrome/pdf:
    post:
      description: |-
        Returns a PDF binary from a `url` or `html` payload (Chrome, legacy).
        "url" or "html" payload in your request. Many options exist for
        injecting cookies, request interceptors, user-agents and waiting for
        selectors, timers and more.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                addScriptTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  anyOf:
                    - $ref: '#/components/schemas/Credentials'
                    - type: 'null'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                emulateMediaType:
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  type: string
                options:
                  additionalProperties: false
                  type: object
                  properties:
                    scale:
                      description: >-
                        Scales the rendering of the web page. Amount must be
                        between `0.1` and `2`.
                      type: number
                    displayHeaderFooter:
                      description: Whether to show the header and footer.
                      type: boolean
                    headerTemplate:
                      description: >-
                        HTML template for the print header. Should be valid HTML
                        with the following

                        classes used to inject values into them:


                        - `date` formatted print date


                        - `title` document title


                        - `url` document location


                        - `pageNumber` current page number


                        - `totalPages` total pages in the document
                      type: string
                    footerTemplate:
                      description: >-
                        HTML template for the print footer. Has the same
                        constraints and support

                        for special classes as {@link
                        PDFOptions.headerTemplate}.
                      type: string
                    printBackground:
                      description: Set to `true` to print background graphics.
                      type: boolean
                    landscape:
                      description: Whether to print in landscape orientation.
                      type: boolean
                    pageRanges:
                      description: Paper ranges to print, e.g. `1-5, 8, 11-13`.
                      type: string
                    format:
                      description: All the valid paper format types when printing a PDF.
                      enum:
                        - A0
                        - A1
                        - A2
                        - A3
                        - A4
                        - A5
                        - A6
                        - LEDGER
                        - LEGAL
                        - LETTER
                        - Ledger
                        - Legal
                        - Letter
                        - TABLOID
                        - Tabloid
                        - a0
                        - a1
                        - a2
                        - a3
                        - a4
                        - a5
                        - a6
                        - ledger
                        - legal
                        - letter
                        - tabloid
                      type: string
                    width:
                      description: >-
                        Sets the width of paper. You can pass in a number or a
                        string with a unit.
                      type:
                        - string
                        - number
                    height:
                      description: >-
                        Sets the height of paper. You can pass in a number or a
                        string with a unit.
                      type:
                        - string
                        - number
                    preferCSSPageSize:
                      description: >-
                        Give any CSS `@page` size declared in the page priority
                        over what is

                        declared in the `width` or `height` or `format` option.
                      type: boolean
                    margin:
                      description: Set the PDF margins.
                      $ref: '#/components/schemas/PDFMargin'
                    omitBackground:
                      description: >-
                        Hides default white background and allows generating
                        pdfs with transparency.
                      type: boolean
                    tagged:
                      description: Generate tagged (accessible) PDF.
                      type: boolean
                    outline:
                      description: Generate document outline.
                      type: boolean
                    timeout:
                      description: >-
                        Timeout in milliseconds. Pass `0` to disable timeout.


                        The default value can be changed by using {@link
                        Page.setDefaultTimeout}
                      type: number
                    waitForFonts:
                      description: >-
                        If true, waits for `document.fonts.ready` to resolve.
                        This might require

                        activating the page using {@link Page.bringToFront} if
                        the page is in the

                        background.
                      type: boolean
                    fullPage:
                      type: boolean
                  description: >-
                    PDF generation options based on Puppeteer's PDFOptions
                    interface.

                    Includes properties like `format`, `landscape`, `margin`,
                    `scale`, etc.
                rejectRequestPattern:
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                            $ref: '#/components/schemas/AnyRecord'
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                setExtraHTTPHeaders:
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  type: boolean
                url:
                  type: string
                userAgent:
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      description: >-
                        Used to specify User Agent Client Hints to emulate. See
                        https://wicg.github.io/ua-client-hints

                        Missing optional values will be filled in by the target
                        with what it would normally use.
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  anyOf:
                    - $ref: '#/components/schemas/Viewport'
                    - type: 'null'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  type: number
              type: object
              example: *ref_0
            example:
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              options:
                scale: 0
                displayHeaderFooter: true
                headerTemplate: string
                footerTemplate: string
                printBackground: true
                landscape: true
                pageRanges: string
                format: A0
                width: string
                height: string
                preferCSSPageSize: true
                margin:
                  top: string
                  bottom: string
                  left: string
                  right: string
                omitBackground: true
                tagged: true
                outline: true
                timeout: 0
                waitForFonts: true
                fullPage: true
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            application/pdf:
              schema:
                description: Responds with an application/pdf content-type and a binary PDF
                type: string
                $schema: http://json-schema.org/draft-07/schema#
          description: Responds with an application/pdf content-type and a binary PDF
        '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: /chrome/pdf
      tags:
        - Chrome (licensed build)
  /chrome/content:
    post:
      description: >-
        Given a `url` or `html` field, loads the page in Chrome and returns the
        fully rendered HTML.
      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: launch
          schema:
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                addScriptTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  anyOf:
                    - $ref: '#/components/schemas/Credentials'
                    - type: 'null'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                emulateMediaType:
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  type: string
                rejectRequestPattern:
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                            $ref: '#/components/schemas/AnyRecord'
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                setExtraHTTPHeaders:
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  description: Whether or not to allow JavaScript to run on the page.
                  type: boolean
                url:
                  type: string
                userAgent:
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      description: >-
                        Used to specify User Agent Client Hints to emulate. See
                        https://wicg.github.io/ua-client-hints

                        Missing optional values will be filled in by the target
                        with what it would normally use.
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  anyOf:
                    - $ref: '#/components/schemas/Viewport'
                    - type: 'null'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  type: number
              type: object
              example: *ref_0
            example:
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            text/html:
              schema:
                description: |-
                  An HTML payload of the website or HTML after JavaScript
                  parsing and execution.
                type: string
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            An HTML payload of the website or HTML after JavaScript
            parsing and execution.
        '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: /chrome/content
      tags:
        - Chrome (licensed build)
  /chrome/scrape:
    post:
      description: >-
        Returns text, HTML, and metadata from a given list of CSS selectors
        against the rendered DOM (Chrome, legacy).

        Debugging information is available by sending in the appropriate flags
        in the "debugOpts"

        property. Responds with an array of JSON objects.
      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: launch
          schema:
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                addScriptTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddScriptTagOptions'
                addStyleTag:
                  type: array
                  items:
                    $ref: '#/components/schemas/FrameAddStyleTagOptions'
                authenticate:
                  anyOf:
                    - $ref: '#/components/schemas/Credentials'
                    - type: 'null'
                  description: >-
                    Credentials for HTTP authentication. Contains `username` and
                    `password` properties.
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieParam'
                debugOpts:
                  $ref: '#/components/schemas/ScrapeDebugOptions'
                elements:
                  type: array
                  items:
                    $ref: '#/components/schemas/ScrapeElementSelector'
                emulateMediaType:
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    Options to configure the page navigation, such as `timeout`
                    and `waitUntil`.
                html:
                  type: string
                rejectRequestPattern:
                  type: array
                  items:
                    type: string
                rejectResourceTypes:
                  type: array
                  items:
                    enum:
                      - cspviolationreport
                      - document
                      - eventsource
                      - fedcm
                      - fetch
                      - font
                      - image
                      - manifest
                      - media
                      - other
                      - ping
                      - prefetch
                      - preflight
                      - script
                      - signedexchange
                      - stylesheet
                      - texttrack
                      - websocket
                      - xhr
                    type: string
                requestInterceptors:
                  type: array
                  items:
                    description: >-
                      An array of patterns (using `req.url().match(r.pattern)`
                      to match) and their

                      corresponding responses to use in order to fulfill those
                      requests.
                    type: object
                    properties:
                      pattern:
                        description: >-
                          An array of patterns (using
                          `req.url().match(r.pattern)` to match) and their

                          corresponding responses to use in order to fulfill
                          those requests.
                        type: string
                      response:
                        additionalProperties: false
                        type: object
                        properties:
                          headers:
                            description: >-
                              Optional response headers.


                              The record values will be converted to string
                              following:

                              Arrays' values will be mapped to String

                              (Used when you need multiple headers with the same
                              name).

                              Non-arrays will be converted to String.
                            $ref: '#/components/schemas/AnyRecord'
                          status:
                            type: number
                          contentType:
                            type: string
                          body:
                            description: >-
                              A string representation of the body to return. Can
                              be a base64-encoded

                              string but please omit any leading content-type
                              data (eg "data:image/png;base64,").
                            type: string
                    additionalProperties: false
                    required:
                      - pattern
                      - response
                setExtraHTTPHeaders:
                  type: object
                  additionalProperties:
                    type: string
                setJavaScriptEnabled:
                  type: boolean
                url:
                  type: string
                userAgent:
                  type: object
                  properties:
                    userAgent:
                      type: string
                    userAgentMetadata:
                      description: >-
                        Used to specify User Agent Client Hints to emulate. See
                        https://wicg.github.io/ua-client-hints

                        Missing optional values will be filled in by the target
                        with what it would normally use.
                      $ref: >-
                        #/components/schemas/Protocol.Emulation.UserAgentMetadata
                    platform:
                      type: string
                  additionalProperties: false
                viewport:
                  anyOf:
                    - $ref: '#/components/schemas/Viewport'
                    - type: 'null'
                  description: >-
                    The viewport dimensions and settings for the page.

                    Includes properties like `width`, `height`,
                    `deviceScaleFactor`, etc.
                waitForEvent:
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  type: number
              type: object
              required:
                - elements
              example: *ref_1
            example:
              addScriptTag:
                - url: string
                  content: string
                  type: string
                  id: string
              addStyleTag:
                - url: string
                  content: string
              authenticate:
                username: string
                password: string
              bestAttempt: true
              cookies:
                - name: string
                  value: string
                  url: string
                  domain: string
                  path: string
                  secure: true
                  httpOnly: true
                  sameSite: Default
                  expires: 0
                  priority: High
                  sourceScheme: NonSecure
                  partitionKey:
                    sourceOrigin: string
                    hasCrossSiteAncestor: true
              debugOpts:
                console: true
                cookies: true
                html: true
                network: true
                screenshot: true
              elements:
                - selector: string
                  timeout: 0
              emulateMediaType: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              html: string
              rejectRequestPattern:
                - string
              rejectResourceTypes:
                - cspviolationreport
              requestInterceptors:
                - pattern: string
                  response:
                    headers: {}
                    status: 0
                    contentType: string
                    body: string
              setExtraHTTPHeaders: {}
              setJavaScriptEnabled: true
              url: string
              userAgent:
                userAgent: string
                userAgentMetadata:
                  brands:
                    - brand: string
                      version: string
                  fullVersionList:
                    - brand: string
                      version: string
                  fullVersion: string
                  platform: string
                  platformVersion: string
                  architecture: string
                  model: string
                  mobile: true
                  bitness: string
                  wow64: true
                  formFactors:
                    - string
                platform: string
              viewport:
                width: 0
                height: 0
                deviceScaleFactor: 0
                isMobile: true
                isLandscape: true
                hasTouch: true
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            application/json:
              schema:
                description: The JSON response body
                type: object
                properties:
                  data:
                    anyOf:
                      - type: array
                        items:
                          type: object
                          properties:
                            results:
                              type: array
                              items:
                                type: object
                                properties:
                                  attributes:
                                    description: A list of HTML attributes of the element
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        name:
                                          description: >-
                                            The name of the HTML attribute for the
                                            element
                                          type: string
                                        value:
                                          description: >-
                                            The value of the HTML attribute for the
                                            element
                                          type: string
                                      additionalProperties: false
                                      required:
                                        - name
                                        - value
                                  height:
                                    description: The height the element
                                    type: number
                                  html:
                                    description: The HTML the element
                                    type: string
                                  left:
                                    description: >-
                                      The amount of pixels from the left of the
                                      page
                                    type: number
                                  text:
                                    description: The text the element
                                    type: string
                                  top:
                                    description: >-
                                      The amount of pixels from the top of the
                                      page
                                    type: number
                                  width:
                                    description: The width the element
                                    type: number
                                additionalProperties: false
                                required:
                                  - attributes
                                  - height
                                  - html
                                  - left
                                  - text
                                  - top
                                  - width
                            selector:
                              description: The DOM selector of the element
                              type: string
                          additionalProperties: false
                          required:
                            - results
                            - selector
                      - type: 'null'
                  debug:
                    description: When debugOpts options are present, results are here
                    anyOf:
                      - type: object
                        properties:
                          console:
                            description: A list of console messages from the browser
                            type: array
                            items:
                              type: string
                          cookies:
                            description: List of cookies for the site or null
                            anyOf:
                              - type: array
                                items:
                                  $ref: '#/components/schemas/Cookie'
                              - type: 'null'
                          html:
                            description: The HTML string of the website or null
                            type:
                              - 'null'
                              - string
                          network:
                            type: object
                            properties:
                              inbound:
                                type: array
                                items:
                                  $ref: '#/components/schemas/InBoundRequest'
                              outbound:
                                type: array
                                items:
                                  $ref: '#/components/schemas/OutBoundRequest'
                            additionalProperties: false
                            required:
                              - inbound
                              - outbound
                          screenshot:
                            description: A base64-encoded string of the site or null
                            type:
                              - 'null'
                              - string
                        additionalProperties: false
                        required:
                          - console
                          - cookies
                          - html
                          - network
                          - screenshot
                      - type: 'null'
                additionalProperties: false
                required:
                  - data
                  - debug
                definitions:
                  Cookie:
                    description: Represents a cookie object.
                    type: object
                    properties:
                      path:
                        description: Cookie path.
                        type: string
                      expires:
                        description: >-
                          Cookie expiration date as the number of seconds since
                          the UNIX epoch. Set to `-1` for

                          session cookies
                        type: number
                      size:
                        description: Cookie size.
                        type: number
                      secure:
                        description: True if cookie is secure.
                        type: boolean
                      session:
                        description: True in case of session cookie.
                        type: boolean
                      partitionKeyOpaque:
                        description: >-
                          True if cookie partition key is opaque. Supported only
                          in Chrome.
                        type: boolean
                      name:
                        description: Cookie name.
                        type: string
                      value:
                        description: Cookie value.
                        type: string
                      domain:
                        description: Cookie domain.
                        type: string
                      httpOnly:
                        description: True if cookie is http-only.
                        type: boolean
                      sameSite:
                        description: Cookie SameSite type.
                        enum:
                          - Default
                          - Lax
                          - None
                          - Strict
                        type: string
                      priority:
                        description: Cookie Priority. Supported only in Chrome.
                        enum:
                          - High
                          - Low
                          - Medium
                        type: string
                      sourceScheme:
                        description: Cookie source scheme type. Supported only in Chrome.
                        enum:
                          - NonSecure
                          - Secure
                          - Unset
                        type: string
                      partitionKey:
                        description: >-
                          Cookie partition key. In Chrome, it matches the
                          top-level site the

                          partitioned cookie is available in. In Firefox, it
                          matches the

                          source origin in the

                          {@link
                          https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey
                          PartitionKey}.
                        anyOf:
                          - $ref: '#/components/schemas/CookiePartitionKey'
                          - type: string
                    additionalProperties: false
                    required:
                      - domain
                      - expires
                      - name
                      - path
                      - secure
                      - session
                      - size
                      - value
                  CookiePartitionKey:
                    description: Represents a cookie partition key in Chrome.
                    type: object
                    properties:
                      sourceOrigin:
                        description: >-
                          The site of the top-level URL the browser was visiting
                          at the start of the request

                          to the endpoint that set the cookie.


                          In Chrome, maps to the CDP's `topLevelSite` partition
                          key.
                        type: string
                      hasCrossSiteAncestor:
                        description: >-
                          Indicates if the cookie has any ancestors that are
                          cross-site to

                          the topLevelSite.


                          Supported only in Chrome.
                        type: boolean
                    additionalProperties: false
                    required:
                      - sourceOrigin
                  InBoundRequest:
                    type: object
                    properties:
                      headers: {}
                      status:
                        type: number
                      url:
                        type: string
                    additionalProperties: false
                    required:
                      - headers
                      - status
                      - url
                  OutBoundRequest:
                    type: object
                    properties:
                      headers: {}
                      method:
                        type: string
                      url:
                        type: string
                    additionalProperties: false
                    required:
                      - headers
                      - method
                      - url
                $schema: http://json-schema.org/draft-07/schema#
          description: The JSON response body
        '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: /chrome/scrape
      tags:
        - Chrome (licensed build)
  /chrome/performance:
    post:
      description: >-
        Run lighthouse performance audits with a supplied "url" in your JSON
        payload.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                budgets:
                  type: array
                  items:
                    type: object
                    properties: {}
                    additionalProperties: true
                config:
                  type: object
                  properties: {}
                  additionalProperties: true
                url:
                  type: string
              type: object
              required:
                - url
              example: *ref_0
            example:
              budgets:
                - {}
              config: {}
              url: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: |-
                  The response of the lighthouse stats. Response objects are
                  determined by the type of budgets and config in the POST
                  JSON body
                type: object
                properties: {}
                additionalProperties: true
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            The response of the lighthouse stats. Response objects are
            determined by the type of budgets and config in the POST
            JSON body
        '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: /chrome/performance
      tags:
        - Chrome (licensed build)
  /chrome/function:
    post:
      description: >-
        Executes a Puppeteer or Playwright script in the Chrome browser context
        and returns the result.

        Browserless sets up a blank page, injects your puppeteer code, and runs
        it.

        You can optionally load external libraries via the "import" module that
        are meant for browser usage.

        Values returned from the function are checked and an appropriate
        content-type and response is sent back

        to your HTTP call.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JSONSchema'
          application/javascript:
            schema:
              type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                description: >-
                  Responses are determined by the returned value of the function

                  itself. Binary responses (PDF's, screenshots) are returned
                  back

                  as binary data, and primitive JavaScript values are returned
                  back

                  by type (HTML data is "text/html", Objects are
                  "application/json")
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            Responses are determined by the returned value of the function
            itself. Binary responses (PDF's, screenshots) are returned back
            as binary data, and primitive JavaScript values are returned back
            by type (HTML data is "text/html", Objects are "application/json")
        '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: /chrome/function
      tags:
        - Chrome (licensed build)
  /chrome/download:
    post:
      description: >-
        Runs a Puppeteer or Playwright script in Chrome and returns any files
        the browser downloaded during execution.

        the execution of puppeteer code, which is ran inside context of the
        browser.

        Browserless sets up a blank page, a fresh download directory, injects
        your puppeteer code, and then executes it.

        You can load external libraries via the "import" syntax, and import
        ESM-style modules

        that are written for execution inside of the browser. Once your script
        is finished, any

        downloaded files from Chromium are returned back with the appropriate
        content-type header.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JSONSchema'
          application/javascript:
            schema:
              type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                description: >-
                  Responses are determined by the returned value of the
                  downloads

                  themselves, so there isn't a static response type for this
                  API.
                $schema: http://json-schema.org/draft-07/schema#
          description: |-
            Responses are determined by the returned value of the downloads
            themselves, so there isn't a static response type for this API.
        '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: /chrome/download
      tags:
        - Chrome (licensed build)
  /chrome/export:
    post:
      description: >-
        Exports a webpage to a PDF or image format. This API is useful for
        generating reports, screenshots, or PDFs of web pages.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            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:
          application/json:
            schema:
              properties:
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless will attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                url:
                  description: The URL of the site you want to archive.
                  type: string
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    An optional goto parameter object for considering when the
                    page is done loading.
                waitForEvent:
                  description: >-
                    Options for waiting for a specific event to be fired on the
                    page.
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  description: Options for waiting for a JavaScript function to execute.
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  description: >-
                    Options for waiting for a specific CSS selector to appear on
                    the page.
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  description: >-
                    The amount of time in milliseconds to wait before
                    proceeding.
                  type: number
                headers:
                  description: >-
                    An object containing additional HTTP headers to send with
                    every request.
                  type: object
                  additionalProperties:
                    type: string
                includeResources:
                  description: >-
                    Whether to include all linked resources (images, CSS, JS) in
                    a zip file.

                    When true, the response will be a zip file containing the
                    HTML and all resources.

                    When false or not provided, the response will be the raw
                    content (default behavior).
                  type: boolean
              type: object
              required:
                - url
              example: *ref_0
            example:
              bestAttempt: true
              url: string
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
              headers: {}
              includeResources: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  html:
                    description: The HTML content of the page.
                    type: string
                additionalProperties: false
                required:
                  - html
                $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: /chrome/export
      tags:
        - Chrome (licensed build)
  /chrome/unblock:
    post:
      description: |-
        Unblocks the provided URL from being blocked due to bot detection.
        Returns a payload of Cookies, HTML, a base64 encoded screenshot,
        and a "browserWSEndpoint" to allow connecting to the browser when
        specified in the JSON Payload. Only supports CDP or Puppeteer
        like libraries when connecting to the "browserWSEndpoint".
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: >-
              Restrict blockAds to a specific set of uBlock ruleset ids
              (comma-separated

              list or JSON array). Only applies when `blockAds` is true. Fewer
              rulesets

              means a faster browser launch under load; omit to load the full
              default set.
            type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: replay
          schema:
            description: >-
              When true, records the unblock session for replay (rrweb) and
              uploads the

              captured replay on cleanup, reusing the same recording pipeline as

              BrowserQL. Like every other Browserless route, replay is a

              connection-level flag supplied via this `?replay=true` query
              parameter

              (the browser's recording config is resolved from the URL at
              launch).

              Defaults to false.
            type: boolean
        - in: query
          name: solveCaptchas
          schema:
            description: >-
              When `browserWSEndpoint` is requested, persists captcha-solving on
              the

              kept-alive session so reconnections automatically solve captchas
              without

              having to re-add `?solveCaptchas=true` to the returned reconnect
              URL.

              Connection-level flag supplied via this `?solveCaptchas=true`
              query

              parameter, mirroring `replay`. Defaults to false.
            type: boolean
        - 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:
          application/json:
            schema:
              properties:
                bestAttempt:
                  description: >-
                    When bestAttempt is set to true, browserless will attempt to
                    proceed

                    when "awaited" events fail or timeout. This includes things
                    like

                    goto, waitForSelector, and more.
                  type: boolean
                url:
                  description: The URL of the site you want to unblock.
                  type: string
                browserWSEndpoint:
                  description: >-
                    Whether or not to keep the underlying browser alive and
                    around for

                    future reconnects. Defaults to false.
                  type: boolean
                cookies:
                  description: >-
                    Whether or not to to return cookies for the site, defaults
                    to true.
                  type: boolean
                content:
                  description: >-
                    Whether or not to to return content for the site, defaults
                    to true.
                  type: boolean
                screenshot:
                  description: >-
                    Whether or not to to return a full-page screenshot for the
                    site, defaults to true.
                  type: boolean
                ttl:
                  description: |-
                    When the browserWSEndpoint is requested this tells
                    browserless how long to keep this browser alive for
                    re-connection until shutting it down completely.
                    Maximum of 30000 for 30 seconds (30,000ms).
                  type: number
                gotoOptions:
                  $ref: '#/components/schemas/GoToOptions'
                  description: >-
                    An optional goto parameter object for considering when the
                    page is done loading.
                waitForEvent:
                  description: >-
                    Options for waiting for a specific event to be fired on the
                    page.
                  type: object
                  properties:
                    event:
                      type: string
                    timeout:
                      type: number
                  additionalProperties: false
                  required:
                    - event
                waitForFunction:
                  description: Options for waiting for a JavaScript function to execute.
                  type: object
                  properties:
                    fn:
                      description: >-
                        The function, or statement, to be evaluated in browser
                        context
                      type: string
                    polling:
                      description: >-
                        An interval at which the pageFunction is executed,
                        defaults to raf.

                        If polling is a number, then it is treated as an
                        interval in milliseconds

                        at which the function would be executed. If polling is a
                        string,

                        then it can be one of the following values: "raf" or
                        "mutation"
                      type:
                        - string
                        - number
                    timeout:
                      description: >-
                        Maximum time to wait for in milliseconds. Defaults to
                        30000 (30 seconds).

                        Pass 0 to disable timeout.
                      type: number
                  additionalProperties: false
                  required:
                    - fn
                waitForSelector:
                  description: >-
                    Options for waiting for a specific CSS selector to appear on
                    the page.
                  type: object
                  properties:
                    hidden:
                      type: boolean
                    selector:
                      type: string
                    timeout:
                      type: number
                    visible:
                      type: boolean
                  additionalProperties: false
                  required:
                    - selector
                waitForTimeout:
                  description: >-
                    The amount of time in milliseconds to wait before
                    proceeding.
                  type: number
              type: object
              required:
                - url
              example: *ref_0
            example:
              bestAttempt: true
              url: string
              browserWSEndpoint: true
              cookies: true
              content: true
              screenshot: true
              ttl: 0
              gotoOptions:
                referer: string
                referrerPolicy: string
                timeout: 0
                waitUntil:
                  - domcontentloaded
                signal:
                  aborted: true
                  onabort: {}
                  reason: {}
              waitForEvent:
                event: string
                timeout: 0
              waitForFunction:
                fn: string
                polling: string
                timeout: 0
              waitForSelector:
                hidden: true
                selector: string
                timeout: 0
                visible: true
              waitForTimeout: 0
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  cookies:
                    description: >-
                      A list of cookies which can be used for new connections or
                      for usage elsewhere.

                      Value is "null" when the request body specifies cookies:
                      false.
                    type: array
                    items:
                      $ref: '#/components/schemas/UnblockCookie'
                  content:
                    description: >-
                      The HTML content of the page once it is passed bot
                      detection.

                      Value is "null" when the request body specifies content:
                      false.
                    type: string
                  browserWSEndpoint:
                    description: >-
                      The browserWSEndpoint of the response when the POST body
                      contains a

                      browserWSEndpoint: true property
                    type: string
                  ttl:
                    description: >-
                      The time the browser will remain alive until it is
                      shutdown. Zero

                      when browserWSEndpoint: false is set in the request
                      payload. The limit

                      is 60000 or 60 seconds, which is the maximum allowed time.
                    type: number
                  screenshot:
                    description: A base64 encoded JPEG of the of the final site page.
                    type: string
                additionalProperties: false
                required:
                  - browserWSEndpoint
                  - content
                  - cookies
                  - screenshot
                  - ttl
                definitions:
                  UnblockCookie:
                    type: object
                    properties:
                      name:
                        type: string
                      value:
                        type: string
                      domain:
                        type: string
                      path:
                        type: string
                      expires:
                        type: number
                      httpOnly:
                        type: boolean
                      secure:
                        type: boolean
                      sameSite:
                        type: string
                      url:
                        type: string
                    additionalProperties: false
                    required:
                      - domain
                      - expires
                      - httpOnly
                      - name
                      - path
                      - sameSite
                      - secure
                      - url
                      - value
                $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: /chrome/unblock
      tags:
        - Chrome (licensed build)
  /chrome:
    get:
      description: >-
        Launch and connect to Chromium with a library like puppeteer or others
        that work over chrome-devtools-protocol.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: integrations
          schema:
            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'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: record
          schema:
            type: boolean
        - in: query
          name: replay
          schema:
            type: boolean
        - in: query
          name: solveCaptchas
          schema:
            type: boolean
        - 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:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chrome
      tags:
        - Chrome (licensed build)
  /chrome/playwright:
    get:
      description: Connect to Chromium with any playwright style library.
      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: 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/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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chrome/playwright
      tags:
        - Chrome (licensed build)
  /chrome/stealth:
    get:
      description: >-
        Launch and connect to Stealthy Chrome with a library like puppeteer or
        others that work over chrome-devtools-protocol for scraping in a more
        stealth-like fashion.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: emulationOs
          schema:
            $ref: '#/components/schemas/Platform'
            description: 'Spoof OS for full per-platform stealth: windows | macos | linux.'
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: integrations
          schema:
            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'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: record
          schema:
            type: boolean
        - in: query
          name: replay
          schema:
            type: boolean
        - in: query
          name: solveCaptchas
          schema:
            type: boolean
        - 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:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chrome/stealth
      tags:
        - Unblock & Stealth
  /chromium/stealth:
    get:
      description: >-
        Launch and connect to Stealthy Chromium with a library like puppeteer or
        others that work over chrome-devtools-protocol for scraping in a more
        stealth-like fashion.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: emulationOs
          schema:
            $ref: '#/components/schemas/Platform'
            description: 'Spoof OS for full per-platform stealth: windows | macos | linux.'
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: integrations
          schema:
            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'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: record
          schema:
            type: boolean
        - in: query
          name: replay
          schema:
            type: boolean
        - in: query
          name: solveCaptchas
          schema:
            type: boolean
        - 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:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chromium/stealth
      tags:
        - Unblock & Stealth
  /stealth:
    get:
      description: >-
        Launch and connect to Stealthy Chromium with a library like puppeteer or
        others that work over chrome-devtools-protocol for scraping in a more
        stealth-like fashion.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: emulationOs
          schema:
            $ref: '#/components/schemas/Platform'
            description: 'Spoof OS for full per-platform stealth: windows | macos | linux.'
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: integrations
          schema:
            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'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: record
          schema:
            type: boolean
        - in: query
          name: replay
          schema:
            type: boolean
        - in: query
          name: solveCaptchas
          schema:
            type: boolean
        - 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:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /stealth
      tags:
        - Unblock & Stealth
  /chrome/live/*:
    get:
      description: >-
        > This API is only available on paid plans. [Sign-up
        here](https://www.browserless.io/pricing/).


        Websocket back-end that powers the live session experience.
      parameters: []
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chrome/live/*
      tags:
        - WebSocket APIs
  /chrome/bql?(/*):
    post:
      description: >-
        Parses and executes BrowserQL requests, powered by the BrowserQL Editor
        or by other API integrations. See the BrowserQL Editor for more
        documentation on this API.
      parameters:
        - in: query
          name: acceptInsecureCerts
          schema:
            description: >-
              Whether to ignore TLS certificate errors (e.g. self-signed or
              untrusted

              authorities) so the browser navigates to sites with invalid
              certificates.
            type: boolean
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: >-
              Restrict blockAds to a specific set of uBlock ruleset ids
              (comma-separated

              list or JSON array). Only applies when `blockAds` is true. Fewer
              rulesets

              means a faster browser launch under load; omit to load the full
              default set.
            type: string
        - in: query
          name: blockConsentModals
          schema:
            description: Whether to automatically block cookie consent modals and popups.
            type: boolean
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: emulationOs
          schema:
            $ref: '#/components/schemas/Platform'
            description: >-
              Spoof OS for the session: 'windows', 'macos', or 'linux'. When
              set, the

              session runs the full per-platform stealth stack (User-Agent, UA
              Client

              Hints, navigator.platform, GPU, fonts, and media/speech/audio
              fingerprints)

              — the same stack the /stealth routes use. Omit for the native
              (Linux) host

              identity.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: humanlike
          schema:
            description: >-
              Whether to enable human-like behavior for interactions.

              When true, actions like typing and clicking will have randomized
              delays.
            type: boolean
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.

              Must be either JSON object, or a base64-encoded JSON object.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: replay
          schema:
            description: |-
              Whether to enable session recording for replay.
              When true, the session will be recorded and can be replayed later.
            type: boolean
        - 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:
          application/json:
            schema:
              properties:
                query:
                  description: The BrowserQL query string to execute.
                  type: string
                operationName:
                  description: >-
                    The name of the operation to execute if the query contains
                    multiple operations.
                  type: string
                variables:
                  description: Variables to pass to the BrowserQL query.
                  type: object
                  additionalProperties: {}
              type: object
              required:
                - query
      responses:
        '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: /chrome/bql?(/*)
      tags:
        - Chrome (licensed build)
      operationId: chrome-bql-execute
    get:
      description: >-
        WebSocket endpoint for BrowserQL. Connect to establish a persistent
        browser

        session, then send multiple GraphQL operations as JSON messages. The
        browser

        and page state persist across all messages for the connection duration.


        Messages use the same JSON format as the HTTP POST endpoint:

        Send: { "query": "mutation { goto(url: \"..\") { status } }",
        "variables": {} }

        Receive: { "data": { "goto": { "status": 200 } } }
      parameters:
        - in: query
          name: acceptInsecureCerts
          schema:
            description: >-
              Whether to ignore TLS certificate errors (e.g. self-signed or
              untrusted

              authorities) so the browser navigates to sites with invalid
              certificates.
            type: boolean
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: >-
              Restrict blockAds to a specific set of uBlock ruleset ids
              (comma-separated

              list or JSON array). Only applies when `blockAds` is true. Fewer
              rulesets

              means a faster browser launch under load; omit to load the full
              default set.
            type: string
        - in: query
          name: blockConsentModals
          schema:
            type: boolean
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: emulationOs
          schema:
            $ref: '#/components/schemas/Platform'
            description: >-
              Spoof OS for the session: 'windows', 'macos', or 'linux'. When
              set, the

              session runs the full per-platform stealth stack (User-Agent, UA
              Client

              Hints, navigator.platform, GPU, fonts, and media/speech/audio
              fingerprints)

              — the same stack the /stealth routes use. Omit for the native
              (Linux) host

              identity.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: humanlike
          schema:
            type: boolean
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.

              Must be either JSON object, or a base64-encoded JSON object.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: replay
          schema:
            type: boolean
        - 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:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chrome/bql?(/*)
      tags:
        - Chrome (licensed build)
      operationId: chrome-bql-connect
  /chromium/agent:
    get:
      description: >-
        WebSocket endpoint for agentic browser interaction. Connect to establish
        a

        persistent browser session, then send JSON-RPC messages to control the
        browser.


        Uses a simple JSON protocol instead of GraphQL:

        Send: { "id": 1, "method": "goto", "params": { "url":
        "https://example.com" } }

        Receive: { "id": 1, "result": { "status": 200, "url":
        "https://example.com" } }


        All BQL mutations are available as methods (goto, click, type,
        screenshot, etc.).

        Additionally supports a "snapshot" method that returns interactive page
        elements

        with CSS selectors, plus tab-management methods (getTabs, switchTab,
        createTab,

        closeTab) for multi-tab workflows.
      parameters:
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: blockConsentModals
          schema:
            type: boolean
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: humanlike
          schema:
            type: boolean
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            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'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: replay
          schema:
            type: boolean
        - in: query
          name: sessionId
          schema:
            description: Attach to a pre-created profile/creation session (autologin).
            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:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chromium/agent
      tags:
        - Browser WebSocket APIs
  /chromium/bql?(/*):
    post:
      description: >-
        Parses and executes BrowserQL requests, powered by the BrowserQL Editor
        or by other API integrations. See the BrowserQL Editor for more
        documentation on this API.
      parameters:
        - in: query
          name: acceptInsecureCerts
          schema:
            description: >-
              Whether to ignore TLS certificate errors (e.g. self-signed or
              untrusted

              authorities) so the browser navigates to sites with invalid
              certificates.
            type: boolean
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: >-
              Restrict blockAds to a specific set of uBlock ruleset ids
              (comma-separated

              list or JSON array). Only applies when `blockAds` is true. Fewer
              rulesets

              means a faster browser launch under load; omit to load the full
              default set.
            type: string
        - in: query
          name: blockConsentModals
          schema:
            description: Whether to automatically block cookie consent modals and popups.
            type: boolean
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: emulationOs
          schema:
            $ref: '#/components/schemas/Platform'
            description: >-
              Spoof OS for the session: 'windows', 'macos', or 'linux'. When
              set, the

              session runs the full per-platform stealth stack (User-Agent, UA
              Client

              Hints, navigator.platform, GPU, fonts, and media/speech/audio
              fingerprints)

              — the same stack the /stealth routes use. Omit for the native
              (Linux) host

              identity.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: humanlike
          schema:
            description: >-
              Whether to enable human-like behavior for interactions.

              When true, actions like typing and clicking will have randomized
              delays.
            type: boolean
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.

              Must be either JSON object, or a base64-encoded JSON object.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: replay
          schema:
            description: |-
              Whether to enable session recording for replay.
              When true, the session will be recorded and can be replayed later.
            type: boolean
        - 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:
          application/json:
            schema:
              properties:
                query:
                  description: The BrowserQL query string to execute.
                  type: string
                operationName:
                  description: >-
                    The name of the operation to execute if the query contains
                    multiple operations.
                  type: string
                variables:
                  description: Variables to pass to the BrowserQL query.
                  type: object
                  additionalProperties: {}
              type: object
              required:
                - query
      responses:
        '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: /chromium/bql?(/*)
      tags:
        - Browser REST APIs
      operationId: chromium-bql-execute
    get:
      description: >-
        WebSocket endpoint for BrowserQL. Connect to establish a persistent
        browser

        session, then send multiple GraphQL operations as JSON messages. The
        browser

        and page state persist across all messages for the connection duration.


        Messages use the same JSON format as the HTTP POST endpoint:

        Send: { "query": "mutation { goto(url: \"..\") { status } }",
        "variables": {} }

        Receive: { "data": { "goto": { "status": 200 } } }
      parameters:
        - in: query
          name: acceptInsecureCerts
          schema:
            description: >-
              Whether to ignore TLS certificate errors (e.g. self-signed or
              untrusted

              authorities) so the browser navigates to sites with invalid
              certificates.
            type: boolean
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: >-
              Restrict blockAds to a specific set of uBlock ruleset ids
              (comma-separated

              list or JSON array). Only applies when `blockAds` is true. Fewer
              rulesets

              means a faster browser launch under load; omit to load the full
              default set.
            type: string
        - in: query
          name: blockConsentModals
          schema:
            type: boolean
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: emulationOs
          schema:
            $ref: '#/components/schemas/Platform'
            description: >-
              Spoof OS for the session: 'windows', 'macos', or 'linux'. When
              set, the

              session runs the full per-platform stealth stack (User-Agent, UA
              Client

              Hints, navigator.platform, GPU, fonts, and media/speech/audio
              fingerprints)

              — the same stack the /stealth routes use. Omit for the native
              (Linux) host

              identity.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: humanlike
          schema:
            type: boolean
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.

              Must be either JSON object, or a base64-encoded JSON object.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: replay
          schema:
            type: boolean
        - 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:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chromium/bql?(/*)
      tags:
        - Browser WebSocket APIs
      operationId: chromium-bql-connect
  /chromium/cli:
    get:
      description: >-
        Interactive hosted-agent chat. Browserless runs the LLM server-side (no

        customer key) and drives a browser to complete the task. Send
        newline-JSON

        control frames ({"type":"start","prompt":"..."}) and receive a stream of

        data / tool_call / tool_result / usage / awaiting_input / end events.
      parameters:
        - in: query
          name: token
          schema:
            type: string
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chromium/cli
      tags:
        - Browser WebSocket APIs
  /chromium/stealth/reconnect/*:
    get:
      description: >-
        Reconnect to an existing stealth browser session (e.g. from /unblock)
        with CDP proxy features like solveCaptchas and stealth-mode fingerprint
        masking.
      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: integrations
          schema:
            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: replay
          schema:
            type: boolean
        - in: query
          name: solveCaptchas
          schema:
            type: boolean
        - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /chromium/stealth/reconnect/*
      tags:
        - Browser WebSocket APIs
  /devtools/browser/*:
    get:
      description: |-
        Connect to an already-running Chromium process with a library like
        puppeteer, or others, that work over chrome-devtools-protocol. Chromium
        must already be launched in order to not return a 404.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /devtools/browser/*
      tags:
        - Browser WebSocket APIs
  /devtools/page/*:
    get:
      description: |-
        Connect to an existing page in Chromium with a library like
        chrome-remote-interface or others that work the page websocketDebugger
        URL. You can get this unique URL by calling the /json/list API
        or by finding the page's unique ID from your library of choice.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /devtools/page/*
      tags:
        - Browser WebSocket APIs
  /function/connect/*:
    get:
      description: >-
        Internally used by the POST /function API to connect the underlying
        client-side code to. Not intended for direct use but documented for
        completeness and to distinguish between other reconnect style calls.
      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: 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'
              - 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
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
      requestBody:
        content: {}
      responses:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /function/connect/*
      tags:
        - Browser WebSocket APIs
  /integrations/script-generator:
    post:
      description: >-
        Generates a Browserless automation script (BrowserQL / Playwright JS /

        Playwright Python) from a natural-language task. A managed agent drives
        a

        browser session; its ordered tool-call transcript is rendered into the

        requested script(s). Streams Server-Sent Events: status, script,
        complete,

        error.
      parameters: []
      requestBody:
        content: {}
      responses:
        '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: /integrations/script-generator
      tags:
        - Integrations
  /session/*:
    delete:
      description: >-
        Deletes a session and its associated data. This will immediately
        terminate any active connections to the session if "force" is applied.


        Query Parameters:

        - force (optional): If true, forces deletion even if the session has
        active connections
      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: force
          schema:
            description: >-
              Whether to force the deletion of the session even if it has active
              connections.

              Defaults to false.
            type: boolean
        - 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:
        '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: /session/*
      tags:
        - Sessions & Connections
      operationId: session-delete
  /stealth/bql?(/*):
    post:
      description: >-
        Parses and executes BrowserQL requests, powered by the BrowserQL Editor
        or by other API integrations. See the BrowserQL Editor for more
        documentation on this API.
      parameters:
        - in: query
          name: acceptInsecureCerts
          schema:
            description: >-
              Whether to ignore TLS certificate errors (e.g. self-signed or
              untrusted

              authorities) so the browser navigates to sites with invalid
              certificates.
            type: boolean
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: >-
              Restrict blockAds to a specific set of uBlock ruleset ids
              (comma-separated

              list or JSON array). Only applies when `blockAds` is true. Fewer
              rulesets

              means a faster browser launch under load; omit to load the full
              default set.
            type: string
        - in: query
          name: blockConsentModals
          schema:
            description: Whether to automatically block cookie consent modals and popups.
            type: boolean
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: emulationOs
          schema:
            $ref: '#/components/schemas/Platform'
            description: >-
              Spoof OS for the session: 'windows', 'macos', or 'linux'. When
              set, the

              session runs the full per-platform stealth stack (User-Agent, UA
              Client

              Hints, navigator.platform, GPU, fonts, and media/speech/audio
              fingerprints)

              — the same stack the /stealth routes use. Omit for the native
              (Linux) host

              identity.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: humanlike
          schema:
            description: >-
              Whether to enable human-like behavior for interactions.

              When true, actions like typing and clicking will have randomized
              delays.
            type: boolean
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.

              Must be either JSON object, or a base64-encoded JSON object.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: replay
          schema:
            description: |-
              Whether to enable session recording for replay.
              When true, the session will be recorded and can be replayed later.
            type: boolean
        - 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:
          application/json:
            schema:
              properties:
                query:
                  description: The BrowserQL query string to execute.
                  type: string
                operationName:
                  description: >-
                    The name of the operation to execute if the query contains
                    multiple operations.
                  type: string
                variables:
                  description: Variables to pass to the BrowserQL query.
                  type: object
                  additionalProperties: {}
              type: object
              required:
                - query
      responses:
        '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: /stealth/bql?(/*)
      tags:
        - Browser REST APIs
      operationId: stealth-bql-execute
    get:
      description: >-
        WebSocket endpoint for BrowserQL. Connect to establish a persistent
        browser

        session, then send multiple GraphQL operations as JSON messages. The
        browser

        and page state persist across all messages for the connection duration.


        Messages use the same JSON format as the HTTP POST endpoint:

        Send: { "query": "mutation { goto(url: \"..\") { status } }",
        "variables": {} }

        Receive: { "data": { "goto": { "status": 200 } } }
      parameters:
        - in: query
          name: acceptInsecureCerts
          schema:
            description: >-
              Whether to ignore TLS certificate errors (e.g. self-signed or
              untrusted

              authorities) so the browser navigates to sites with invalid
              certificates.
            type: boolean
        - in: query
          name: allowedDomains
          schema:
            description: >-
              Optional per-connection narrowing of the integration's
              allowed-domain list.

              Extracted from the JSON `allowedDomains` query parameter. Can only
              narrow the

              integration's domains, never widen them.
            type: array
            items:
              type: string
        - 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: >-
              Restrict blockAds to a specific set of uBlock ruleset ids
              (comma-separated

              list or JSON array). Only applies when `blockAds` is true. Fewer
              rulesets

              means a faster browser launch under load; omit to load the full
              default set.
            type: string
        - in: query
          name: blockConsentModals
          schema:
            type: boolean
        - in: query
          name: credentials
          schema:
            $ref: '#/components/schemas/StringRecord'
            description: >-
              Optional alias → `op://…` reference map for the integration above.
              Extracted

              from the JSON `credentials` query parameter. References are not
              secret;

              resolved values are never stored here. Optional — a connection can
              also pass

              raw `op://…` references straight to Browserless.loadSecret.
        - in: query
          name: emulationOs
          schema:
            $ref: '#/components/schemas/Platform'
            description: >-
              Spoof OS for the session: 'windows', 'macos', or 'linux'. When
              set, the

              session runs the full per-platform stealth stack (User-Agent, UA
              Client

              Hints, navigator.platform, GPU, fonts, and media/speech/audio
              fingerprints)

              — the same stack the /stealth routes use. Omit for the native
              (Linux) host

              identity.
        - in: query
          name: externalProxyServer
          schema:
            description: >-
              External proxy server URL for user-provided proxies.

              Format: http(s)://[username:password@]host:port

              When set, routes requests through this proxy instead of built-in
              residential proxies.
            type: string
        - in: query
          name: humanlike
          schema:
            type: boolean
        - in: query
          name: integrationId
          schema:
            description: >-
              Optional 1Password integration id for credential filling on a
              non-persistent

              connection. Extracted from the `integrationId` query parameter;
              the persistent

              session path carries the same data on session metadata instead.
            type: string
        - in: query
          name: launch
          schema:
            description: >-
              Launch options for the browser, either as a JSON object or a JSON
              string.

              Includes options like `headless`, `args`, `defaultViewport`, etc.

              Must be either JSON object, or a base64-encoded JSON object.
            anyOf:
              - $ref: '#/components/schemas/CDPLaunchOptions'
              - 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: proxy
          schema:
            $ref: '#/components/schemas/ProxyType'
            description: 'The type of proxy to use: ''residential'' or ''datacenter''.'
        - in: query
          name: proxyCity
          schema:
            description: >-
              The city to use for the proxy.


              Available cities:
              https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN

              Documentation:
              https://docs.browserless.io/baas/features/proxies#built-in-residential-proxy
            type: string
        - in: query
          name: proxyCountry
          schema:
            description: >-
              A two-letter country code for the proxy configuration.


              Supported codes: US, GB, FR, DE, etc.

              Full list:
              https://docs.browserless.io/bql-schema/types/enums/country-type
            type: string
        - in: query
          name: proxyLocaleMatch
          schema:
            description: >-
              Sets the browser's language to match the proxy's geographic
              location.

              Recommended when using proxyCountry to ensure websites render
              content,

              currency, and formatting in the local language. Default is English
              (en-US).
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: proxyPreset
          schema:
            description: >-
              A preset code for website-specific proxy routing.

              Maps to specific proxy vendors internally for optimal access to
              certain websites.

              Format: "px_<identifier>" (e.g., "px_gov01", "px_amazon01")
            type: string
        - in: query
          name: proxyState
          schema:
            description: >-
              The state or province to use for the proxy, whitespace must be
              replaced with underscores
            type: string
        - in: query
          name: proxySticky
          schema:
            description: >-
              Whether or not to use the same IP for all requests, defaults to
              true
            enum:
              - '0'
              - '1'
              - 'false'
              - 'true'
            type: string
        - in: query
          name: replay
          schema:
            type: boolean
        - 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:
        '101':
          description: Indicates successful WebSocket upgrade.
        '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: /stealth/bql?(/*)
      tags:
        - Browser WebSocket APIs
      operationId: stealth-bql-connect
servers:
  - url: https://production-sfo.browserless.io
components:
  schemas:
    FrameAddScriptTagOptions:
      type: object
      properties:
        url:
          description: URL of the script to be added.
          type: string
        content:
          description: JavaScript to be injected into the frame.
          type: string
        type:
          description: >-
            Sets the `type` of the script. Use `module` in order to load an
            ES2015 module.
          type: string
        id:
          description: Sets the `id` of the script.
          type: string
      additionalProperties: false
    FrameAddStyleTagOptions:
      type: object
      properties:
        url:
          description: the URL of the CSS file to be added.
          type: string
        content:
          description: Raw CSS content to be injected into the frame.
          type: string
      additionalProperties: false
    Credentials:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
      additionalProperties: false
      required:
        - password
        - username
    CookieParam:
      description: |-
        Cookie parameter object used to set cookies in the page-level cookies
        API.
      type: object
      properties:
        name:
          description: Cookie name.
          type: string
        value:
          description: Cookie value.
          type: string
        url:
          description: >-
            The request-URI to associate with the setting of the cookie. This
            value can affect

            the default domain, path, and source scheme values of the created
            cookie.
          type: string
        domain:
          description: Cookie domain.
          type: string
        path:
          description: Cookie path.
          type: string
        secure:
          description: True if cookie is secure.
          type: boolean
        httpOnly:
          description: True if cookie is http-only.
          type: boolean
        sameSite:
          description: Cookie SameSite type.
          enum:
            - Default
            - Lax
            - None
            - Strict
          type: string
        expires:
          description: Cookie expiration date, session cookie if not set
          type: number
        priority:
          description: Cookie Priority. Supported only in Chrome.
          enum:
            - High
            - Low
            - Medium
          type: string
        sourceScheme:
          description: Cookie source scheme type. Supported only in Chrome.
          enum:
            - NonSecure
            - Secure
            - Unset
          type: string
        partitionKey:
          description: >-
            Cookie partition key. In Chrome, it matches the top-level site the

            partitioned cookie is available in. In Firefox, it matches the

            source origin in the

            {@link
            https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey
            PartitionKey}.
          anyOf:
            - $ref: '#/components/schemas/CookiePartitionKey'
            - type: string
      additionalProperties: false
      required:
        - name
        - value
    CookiePartitionKey:
      description: Represents a cookie partition key in Chrome.
      type: object
      properties:
        sourceOrigin:
          description: >-
            The site of the top-level URL the browser was visiting at the start
            of the request

            to the endpoint that set the cookie.


            In Chrome, maps to the CDP's `topLevelSite` partition key.
          type: string
        hasCrossSiteAncestor:
          description: |-
            Indicates if the cookie has any ancestors that are cross-site to
            the topLevelSite.

            Supported only in Chrome.
          type: boolean
      additionalProperties: false
      required:
        - sourceOrigin
    GoToOptions:
      type: object
      properties:
        referer:
          description: >-
            If provided, it will take preference over the referer header value
            set by

            {@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}.
          type: string
        referrerPolicy:
          description: >-
            If provided, it will take preference over the referer-policy header
            value

            set by {@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}.
          type: string
        timeout:
          description: >-
            Maximum wait time in milliseconds. Pass 0 to disable the timeout.


            The default value can be changed by using the

            {@link Page.setDefaultTimeout} or {@link
            Page.setDefaultNavigationTimeout}

            methods.
          type: number
        waitUntil:
          description: >-
            When to consider waiting succeeds. Given an array of event strings,
            waiting

            is considered to be successful after all events have been fired.
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/PuppeteerLifeCycleEvent'
            - enum:
                - domcontentloaded
                - load
                - networkidle0
                - networkidle2
              type: string
        signal:
          description: A signal object that allows you to cancel the call.
          $ref: '#/components/schemas/AbortSignal'
      additionalProperties: false
    PuppeteerLifeCycleEvent:
      enum:
        - domcontentloaded
        - load
        - networkidle0
        - networkidle2
      type: string
    AbortSignal:
      type: object
      properties:
        aborted:
          type: boolean
        onabort:
          anyOf:
            - type: object
              additionalProperties: false
            - type: 'null'
        reason: {}
      additionalProperties: false
      required:
        - aborted
        - onabort
        - reason
    Protocol.Emulation.UserAgentMetadata:
      description: >-
        Used to specify User Agent Client Hints to emulate. See
        https://wicg.github.io/ua-client-hints

        Missing optional values will be filled in by the target with what it
        would normally use.
      type: object
      properties:
        brands:
          description: Brands appearing in Sec-CH-UA.
          type: array
          items:
            $ref: '#/components/schemas/Protocol.Emulation.UserAgentBrandVersion'
        fullVersionList:
          description: Brands appearing in Sec-CH-UA-Full-Version-List.
          type: array
          items:
            $ref: '#/components/schemas/Protocol.Emulation.UserAgentBrandVersion'
        fullVersion:
          type: string
        platform:
          type: string
        platformVersion:
          type: string
        architecture:
          type: string
        model:
          type: string
        mobile:
          type: boolean
        bitness:
          type: string
        wow64:
          type: boolean
        formFactors:
          description: |-
            Used to specify User Agent form-factor values.
            See https://wicg.github.io/ua-client-hints/#sec-ch-ua-form-factors
          type: array
          items:
            type: string
      additionalProperties: false
      required:
        - architecture
        - mobile
        - model
        - platform
        - platformVersion
    Protocol.Emulation.UserAgentBrandVersion:
      description: >-
        Used to specify User Agent Client Hints to emulate. See
        https://wicg.github.io/ua-client-hints
      type: object
      properties:
        brand:
          type: string
        version:
          type: string
      additionalProperties: false
      required:
        - brand
        - version
    Viewport:
      type: object
      properties:
        width:
          description: The page width in CSS pixels.
          type: number
        height:
          description: The page height in CSS pixels.
          type: number
        deviceScaleFactor:
          description: >-
            Specify device scale factor.

            See {@link
            https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio
            devicePixelRatio} for more info.
          type: number
        isMobile:
          description: Whether the `meta viewport` tag is taken into account.
          type: boolean
        isLandscape:
          description: Specifies if the viewport is in landscape mode.
          type: boolean
        hasTouch:
          description: Specify if the viewport supports touch events.
          type: boolean
      additionalProperties: false
      required:
        - height
        - width
    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
        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
    JSONSchema:
      type: object
      properties:
        code:
          type: string
        context:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ContextValue'
      additionalProperties: false
      required:
        - code
    ContextValue:
      anyOf:
        - type: array
          items:
            $ref: '#/components/schemas/ContextValue'
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/ContextValue'
        - type:
            - 'null'
            - string
            - number
            - boolean
    PDFMargin:
      type: object
      properties:
        top:
          type:
            - string
            - number
        bottom:
          type:
            - string
            - number
        left:
          type:
            - string
            - number
        right:
          type:
            - string
            - number
      additionalProperties: false
    ScrapeDebugOptions:
      type: object
      properties:
        console:
          type: boolean
        cookies:
          type: boolean
        html:
          type: boolean
        network:
          type: boolean
        screenshot:
          type: boolean
      additionalProperties: false
    ScrapeElementSelector:
      type: object
      properties:
        selector:
          type: string
        timeout:
          type: number
      additionalProperties: false
      required:
        - selector
    Cookie:
      description: Represents a cookie object.
      type: object
      properties:
        path:
          description: Cookie path.
          type: string
        expires:
          description: >-
            Cookie expiration date as the number of seconds since the UNIX
            epoch. Set to `-1` for

            session cookies
          type: number
        size:
          description: Cookie size.
          type: number
        secure:
          description: True if cookie is secure.
          type: boolean
        session:
          description: True in case of session cookie.
          type: boolean
        partitionKeyOpaque:
          description: True if cookie partition key is opaque. Supported only in Chrome.
          type: boolean
        name:
          description: Cookie name.
          type: string
        value:
          description: Cookie value.
          type: string
        domain:
          description: Cookie domain.
          type: string
        httpOnly:
          description: True if cookie is http-only.
          type: boolean
        sameSite:
          description: Cookie SameSite type.
          enum:
            - Default
            - Lax
            - None
            - Strict
          type: string
        priority:
          description: Cookie Priority. Supported only in Chrome.
          enum:
            - High
            - Low
            - Medium
          type: string
        sourceScheme:
          description: Cookie source scheme type. Supported only in Chrome.
          enum:
            - NonSecure
            - Secure
            - Unset
          type: string
        partitionKey:
          description: >-
            Cookie partition key. In Chrome, it matches the top-level site the

            partitioned cookie is available in. In Firefox, it matches the

            source origin in the

            {@link
            https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey
            PartitionKey}.
          anyOf:
            - $ref: '#/components/schemas/CookiePartitionKey'
            - type: string
      additionalProperties: false
      required:
        - domain
        - expires
        - name
        - path
        - secure
        - session
        - size
        - value
    InBoundRequest:
      type: object
      properties:
        headers: {}
        status:
          type: number
        url:
          type: string
      additionalProperties: false
      required:
        - headers
        - status
        - url
    OutBoundRequest:
      type: object
      properties:
        headers: {}
        method:
          type: string
        url:
          type: string
      additionalProperties: false
      required:
        - headers
        - method
        - url
    ScreenshotOptions:
      type: object
      properties:
        optimizeForSpeed:
          type: boolean
        type:
          enum:
            - jpeg
            - png
            - webp
          type: string
        quality:
          description: Quality of the image, between 0-100. Not applicable to `png` images.
          type: number
        fromSurface:
          description: Capture the screenshot from the surface, rather than the view.
          type: boolean
        fullPage:
          description: When `true`, takes a screenshot of the full page.
          type: boolean
        omitBackground:
          description: >-
            Hides default white background and allows capturing screenshots with
            transparency.
          type: boolean
        clip:
          description: Specifies the region of the page/element to clip.
          $ref: '#/components/schemas/ScreenshotClip'
        encoding:
          description: Encoding of the image.
          enum:
            - base64
            - binary
          type: string
        captureBeyondViewport:
          description: Capture the screenshot beyond the viewport.
          type: boolean
      additionalProperties: false
    ScreenshotClip:
      type: object
      properties:
        scale:
          type: number
        width:
          description: the width of the element in pixels.
          type: number
        height:
          description: the height of the element in pixels.
          type: number
        x:
          type: number
        'y':
          type: number
      additionalProperties: false
      required:
        - height
        - width
        - x
        - 'y'
    ProxyType:
      description: >-
        The proxy networks the platform can route through. `residential` uses
        the

        built-in residential vendors; `datacenter` uses the Geonode datacenter

        network (cheaper, billed at a lower per-MB rate).
      enum:
        - datacenter
        - residential
      type: string
    UnblockCookie:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        domain:
          type: string
        path:
          type: string
        expires:
          type: number
        httpOnly:
          type: boolean
        secure:
          type: boolean
        sameSite:
          type: string
        url:
          type: string
      additionalProperties: false
      required:
        - domain
        - expires
        - httpOnly
        - name
        - path
        - sameSite
        - secure
        - url
        - value
    PaperFormat:
      description: All the valid paper format types when printing a PDF.
      enum:
        - A0
        - A1
        - A2
        - A3
        - A4
        - A5
        - A6
        - LEDGER
        - LEGAL
        - LETTER
        - Ledger
        - Legal
        - Letter
        - TABLOID
        - Tabloid
        - a0
        - a1
        - a2
        - a3
        - a4
        - a5
        - a6
        - ledger
        - legal
        - letter
        - tabloid
      type: string
    CookieSameSite_2:
      description: |-
        Represents the cookie's 'SameSite' status:
        https://tools.ietf.org/html/draft-west-first-party-cookies
      enum:
        - Default
        - Lax
        - None
        - Strict
      type: string
    CookiePriority:
      description: |-
        Represents the cookie's 'Priority' status:
        https://tools.ietf.org/html/draft-west-cookie-priority-00
      enum:
        - High
        - Low
        - Medium
      type: string
    CookieSourceScheme:
      description: >-
        Represents the source scheme of the origin that originally set the
        cookie. A value of

        "Unset" allows protocol clients to emulate legacy cookie scope for the
        scheme.

        This is a temporary ability and it will be removed in the future.
      enum:
        - NonSecure
        - Secure
        - Unset
      type: string
    ImageFormat:
      enum:
        - jpeg
        - png
        - webp
      type: string
    SearchResponseData:
      type: object
      properties:
        web:
          type: array
          items:
            $ref: '#/components/schemas/WebSearchResult'
        news:
          type: array
          items:
            $ref: '#/components/schemas/NewsSearchResult'
        images:
          type: array
          items:
            $ref: '#/components/schemas/ImageSearchResult'
      additionalProperties: false
    WebSearchResult:
      type: object
      properties:
        title:
          type: string
        url:
          type: string
        description:
          type: string
        position:
          type: number
        markdown:
          type: string
        html:
          type: string
        links:
          type: array
          items:
            type: string
        screenshot:
          type: string
        metadata:
          type: object
          properties:
            statusCode:
              type: number
            strategy:
              type: string
            error:
              type: string
          additionalProperties: false
          required:
            - statusCode
      additionalProperties: false
      required:
        - description
        - title
        - url
    NewsSearchResult:
      type: object
      properties:
        date:
          type: string
        imageUrl:
          type: string
        title:
          type: string
        url:
          type: string
        description:
          type: string
        position:
          type: number
        markdown:
          type: string
        html:
          type: string
        links:
          type: array
          items:
            type: string
        screenshot:
          type: string
        metadata:
          type: object
          properties:
            statusCode:
              type: number
            strategy:
              type: string
            error:
              type: string
          additionalProperties: false
          required:
            - statusCode
      additionalProperties: false
      required:
        - description
        - title
        - url
    ImageSearchResult:
      type: object
      properties:
        title:
          type: string
        imageUrl:
          type: string
        imageWidth:
          type: number
        imageHeight:
          type: number
        url:
          type: string
        position:
          type: number
      additionalProperties: false
    Platform:
      enum:
        - linux
        - macos
        - windows
      type: string
    CrawlStatus:
      enum:
        - cancelled
        - completed
        - failed
        - in-progress
      type: string
    CrawlPageResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/PageStatus'
        contentUrl:
          type: string
        metadata:
          type: object
          properties:
            title:
              type: string
            description:
              type: string
            language:
              type: string
            scrapedAt:
              type: string
            sourceURL:
              type: string
            statusCode:
              type: number
            error:
              type: string
          additionalProperties: false
          required:
            - description
            - error
            - language
            - scrapedAt
            - sourceURL
            - statusCode
            - title
      additionalProperties: false
      required:
        - contentUrl
        - metadata
        - status
    PageStatus:
      enum:
        - cancelled
        - completed
        - failed
        - in-progress
        - queued
      type: string
    CrawlListItem:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        status:
          $ref: '#/components/schemas/CrawlStatus'
        total:
          type: number
        completed:
          type: number
        createdAt:
          type: string
        completedAt:
          type: string
      additionalProperties: false
      required:
        - completed
        - completedAt
        - createdAt
        - id
        - status
        - total
        - url
    ProfileResponse:
      description: |-
        Public-facing profile response returned by HTTP routes.
        Omits internal fields like token_hash and storage_key.
      type: object
      properties:
        id:
          description: Unique profile identifier.
          type: string
        name:
          description: User-supplied profile name. Unique per token.
          type: string
        cookieCount:
          description: Number of cookies captured in the profile.
          type: number
        originCount:
          description: Number of distinct origins with stored localStorage or IndexedDB.
          type: number
        lastUsedAt:
          description: >-
            ISO timestamp of the last time this profile was applied to a
            session, or null if never used.
          type: string
        createdAt:
          description: ISO timestamp of when the profile was created.
          type: string
        updatedAt:
          description: ISO timestamp of the last metadata change (e.g., rename).
          type: string
      additionalProperties: false
      required:
        - cookieCount
        - createdAt
        - id
        - lastUsedAt
        - name
        - originCount
        - updatedAt
    RefreshResponseDiagnostics:
      description: |-
        Per-entry counts of cookies, origins, and IndexedDB items the server
        dropped or truncated before persisting. All zero on a clean refresh.
      type: object
      properties:
        skippedMalformedCookies:
          description: Cookies dropped because required fields were missing or wrong type.
          type: number
        skippedPrivateCookies:
          description: >-
            Cookies dropped because their domain pointed at a private/internal
            host.
          type: number
        skippedMalformedOrigins:
          description: Origins dropped because they were malformed or non-http(s).
          type: number
        skippedPrivateOrigins:
          description: Origins dropped because they targeted a private/internal network.
          type: number
        truncatedOrigins:
          description: Origins dropped because the per-profile cap was exceeded.
          type: number
        skippedMalformedIdbDatabases:
          description: IndexedDB databases dropped because required fields were missing.
          type: number
        truncatedIdbDatabases:
          description: IndexedDB databases dropped because the per-origin cap was exceeded.
          type: number
        skippedMalformedIdbStores:
          description: >-
            IndexedDB object-stores dropped because required fields were
            missing.
          type: number
        truncatedIdbEntries:
          description: IndexedDB entries dropped because the per-store cap was exceeded.
          type: number
      additionalProperties: false
      required:
        - skippedMalformedCookies
        - skippedMalformedIdbDatabases
        - skippedMalformedIdbStores
        - skippedMalformedOrigins
        - skippedPrivateCookies
        - skippedPrivateOrigins
        - truncatedIdbDatabases
        - truncatedIdbEntries
        - truncatedOrigins
    UploadResponseDiagnostics:
      description: |-
        Per-entry counts of cookies, origins, and IndexedDB items the server
        dropped or truncated before persisting. All zero on a clean upload.
      type: object
      properties:
        skippedMalformedCookies:
          description: Cookies dropped because required fields were missing or wrong type.
          type: number
        skippedPrivateCookies:
          description: >-
            Cookies dropped because their domain pointed at a private/internal
            host.
          type: number
        skippedMalformedOrigins:
          description: Origins dropped because they were malformed or non-http(s).
          type: number
        skippedPrivateOrigins:
          description: Origins dropped because they targeted a private/internal network.
          type: number
        truncatedOrigins:
          description: Origins dropped because the per-profile cap was exceeded.
          type: number
        skippedMalformedIdbDatabases:
          description: IndexedDB databases dropped because required fields were missing.
          type: number
        truncatedIdbDatabases:
          description: IndexedDB databases dropped because the per-origin cap was exceeded.
          type: number
        skippedMalformedIdbStores:
          description: >-
            IndexedDB object-stores dropped because required fields were
            missing.
          type: number
        truncatedIdbEntries:
          description: IndexedDB entries dropped because the per-store cap was exceeded.
          type: number
      additionalProperties: false
      required:
        - skippedMalformedCookies
        - skippedMalformedIdbDatabases
        - skippedMalformedIdbStores
        - skippedMalformedOrigins
        - skippedPrivateCookies
        - skippedPrivateOrigins
        - truncatedIdbDatabases
        - truncatedIdbEntries
        - truncatedOrigins
    OpAuditLogResponse:
      description: >-
        Public-facing audit-log entry returned by the audit HTTP route. Omits

        token_hash — never includes any token material — and carries the
        credential

        reference plus non-secret target metadata only.
      type: object
      properties:
        id:
          description: Unique audit-entry identifier.
          type: string
        integrationId:
          description: Integration this fill attempt was made through.
          type: string
        profileId:
          description: Authentication profile the fill targeted, or null.
          type: string
        secretRef:
          description: The alias or op:// reference requested. Never a resolved value.
          type: string
        targetOrigin:
          description: Document origin the fill was attempted on, or null.
          type: string
        targetSelector:
          description: CSS selector supplied by the caller, or null.
          type: string
        targetDescriptor:
          description: Non-secret descriptor of the focused element, or null.
          type: string
        outcome:
          $ref: '#/components/schemas/OpAuditOutcome'
          description: '`success` if the value was filled, otherwise `failure`.'
        errorCode:
          description: Error code when the outcome is `failure`, otherwise null.
          type: string
        createdAt:
          description: ISO timestamp of the attempt.
          type: string
      additionalProperties: false
      required:
        - createdAt
        - errorCode
        - id
        - integrationId
        - outcome
        - profileId
        - secretRef
        - targetDescriptor
        - targetOrigin
        - targetSelector
    OpAuditOutcome:
      description: Outcome recorded for a single Browserless.loadSecret attempt.
      enum:
        - failure
        - success
      type: string
    OpIntegrationKind:
      enum:
        - connect
        - service_account
      type: string
    OpIntegrationResponse:
      description: |-
        Public-facing integration response returned by HTTP routes.
        Omits internal fields — never includes token_hash or any token material.
      type: object
      properties:
        id:
          description: Unique integration identifier.
          type: string
        label:
          description: User-supplied label. Unique per token.
          type: string
        kind:
          $ref: '#/components/schemas/OpIntegrationKind'
          description: 'Integration kind: `service_account` (default) or `connect`.'
        allowedDomains:
          description: Origins this integration is allowed to fill into.
          type: array
          items:
            type: string
        connectUrl:
          description: Connect server URL when kind is `connect`, otherwise null.
          type: string
        expiresAt:
          description: >-
            ISO timestamp after which the integration is treated as expired, or
            null.
          type: string
        lastResolvedAt:
          description: >-
            ISO timestamp of the last successful secret resolve, or null if
            never used.
          type: string
        createdAt:
          description: ISO timestamp of when the integration was created.
          type: string
        updatedAt:
          description: ISO timestamp of the last metadata change.
          type: string
      additionalProperties: false
      required:
        - allowedDomains
        - connectUrl
        - createdAt
        - expiresAt
        - id
        - kind
        - label
        - lastResolvedAt
        - updatedAt
    AutologinState:
      description: Lifecycle state of an autologin task.
      enum:
        - failed
        - pending
        - running
        - success
      type: string
    AutologinDomainResult:
      type: object
      properties:
        origin:
          type: string
        status:
          $ref: '#/components/schemas/AutologinDomainStatus'
        error:
          type: string
      additionalProperties: false
      required:
        - origin
        - status
    AutologinDomainStatus:
      description: |-
        Per-origin progress/outcome as the agent works through the domain list.
        Live: `pending` (not reached), `active` (currently attempting), `tried`
        (moved past — outcome not yet known). Terminal: `success` | `failed`.
      enum:
        - active
        - failed
        - pending
        - success
        - tried
      type: string
    StringRecord:
      type: object
      additionalProperties: false
    AnyRecord:
      type: object
      additionalProperties: false
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: query
      name: token
      description: >-
        Your Browserless API token. Find it on your [Account
        dashboard](https://www.browserless.io/account).
security:
  - tokenAuth: []
tags:
  - name: Screenshots & PDFs
    description: >-
      Capture full-page or element screenshots and generate PDFs from web pages.
      The root `/screenshot` and `/pdf` routes work for most cases. Use
      browser-specific variants like `/edge/screenshot` when you need a
      particular engine.
    x-displayName: Screenshots & PDFs
  - name: Scraping & Content
    description: >-
      Load pages and extract HTML, text, or structured data. `/chromium/content`
      returns raw HTML. `/chromium/scrape` runs `querySelectorAll` against the
      rendered DOM and returns matched elements. `/smart-scrape` cascades
      through multiple extraction strategies automatically.
    x-displayName: Scraping & Content
  - name: Functions & Downloads
    description: >-
      Run custom JavaScript in a browser context and retrieve the resulting
      files. Use `/function` to execute a Puppeteer or Playwright script
      server-side, and `/download` to capture binary assets triggered by in-page
      actions.
    x-displayName: Functions & Downloads
  - name: Sessions & Connections
    description: >-
      Create persistent browser sessions, reconnect to running browsers, and
      query CDP metadata. `/session` spins up a session that outlives a single
      WebSocket connection. `/reconnect/:id` reattaches to it later.
    x-displayName: Sessions & Connections
  - name: Crawling
    description: >-
      Launch, monitor, and cancel multi-page crawl jobs. `POST /crawl` starts a
      crawl, `GET /crawl/:id` polls for progress, and `DELETE /crawl/:id`
      cancels it.
    x-displayName: Crawling
  - name: Unblock & Stealth
    description: >-
      Bypass bot detection and anti-scraping measures. `/unblock` handles
      aggressive anti-bot challenges end-to-end. The BQL stealth variants
      (`/chromium/bql`, `/chrome/bql`) randomize browser fingerprints for
      longer-running automation.
    x-displayName: Unblock & Stealth
  - name: Browser Management
    description: >-
      Inspect running sessions, terminate browsers, and retrieve server
      metadata. `/active` lists current sessions, `/kill/:id` terminates one,
      and `/meta` returns server configuration.
    x-displayName: Browser Management
  - name: Profiles
    description: >-
      Create and manage persistent browser profiles that preserve cookies,
      localStorage, and IndexedDB across sessions. Capture a logged-in state
      once with `Browserless.saveProfile`, then rehydrate it on any future
      session with `?profile=<name>`.
    x-displayName: Profiles
  - 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
  - name: Integrations
    description: >-
      Connect external services to browser sessions. Currently supports
      1Password for injecting stored credentials into a session without exposing
      secrets in your code.
    x-displayName: Integrations
  - name: Chrome (licensed build)
    description: >-
      The `/chrome/*` endpoints use the licensed Google Chrome binary, which
      includes proprietary codec and DRM support. Use these when a site requires
      Chrome-specific features, video codecs (Twitch, YouTube, Netflix), or
      enhanced bot detection evasion. For most automation tasks, the
      `/chromium/*` equivalents work identically.
    x-displayName: Chrome (licensed build)
  - name: WebSocket APIs
    description: >-
      Connect Puppeteer, Playwright, or raw DevTools Protocol clients over
      WebSocket. Launch a browser with `wss://` and get back a CDP session for
      full programmatic control.
    x-displayName: WebSocket APIs
  - name: CDP Extensions
    description: >-
      Browserless-specific Chrome DevTools Protocol methods you call via
      `cdp.send()` in Puppeteer or Playwright sessions. These extend the
      standard CDP with live URLs, captcha solving, session reconnect, profile
      management, and page identification.


      ## Usage


      ```javascript

      const browser = await puppeteer.connect({ browserWSEndpoint: '...' });

      const [page] = await browser.pages();

      const cdp = await page.createCDPSession();


      // Example: Get a live URL for debugging

      const { liveURL } = await cdp.send('Browserless.liveURL', { quality: 75
      });

      ```


      ## Browserless.liveURL


      Returns a URL that opens a live, interactive view of the current browser
      session in any browser. Use this for debugging, QA, or human-in-the-loop
      workflows. The returned URL is temporary and tied to the session's
      lifetime.


      Call via CDP: `cdp.send('Browserless.liveURL', { quality: 75 })`


      Returns: `{ liveURL: 'https://...' }`


      | Parameter | Type | Description |

      |---|---|---|

      | `quality` | `number` | JPEG quality for the live stream (1-100). Default
      75. |

      | `format` | `string` | Image format for the live stream frames. |


      ## Browserless.closeLiveURL


      Closes a previously opened liveURL, freeing server resources. Called
      automatically when the browser session ends.


      Call via CDP: `cdp.send('Browserless.closeLiveURL')`


      ## Browserless.solveCaptcha


      Detects any CAPTCHA challenges on the current page and attempts to solve
      them using third-party solving services. Supports reCAPTCHA v2/v3,
      hCaptcha, Cloudflare Turnstile, and more.


      Call via CDP: `cdp.send('Browserless.solveCaptcha', { type: 'hcaptcha',
      wait: true })`


      Returns: `{ solved: true, token: '...' }`


      | Parameter | Type | Description |

      |---|---|---|

      | `type` | `string` | CAPTCHA type to solve. Omit to auto-detect. |

      | `wait` | `boolean` | Wait for the CAPTCHA to be fully solved before
      returning. Default true. |


      ## Browserless.foundCaptcha


      Scans the current page for known CAPTCHA patterns and returns detection
      results without solving.


      Call via CDP: `cdp.send('Browserless.foundCaptcha')`


      Returns: `{ found: true, type: 'hcaptcha' }`


      ## Browserless.reconnect


      Returns a WebSocket URL for reconnecting to the current browser session
      after disconnecting. The session stays alive on the server for the
      duration of its TTL.


      Call via CDP: `cdp.send('Browserless.reconnect', { timeout: 60000 })`


      Returns: `{ browserWSEndpoint: 'wss://...' }`


      | Parameter | Type | Description |

      |---|---|---|

      | `timeout` | `number` | How long (ms) to keep the session alive after
      disconnect. Default 60000. |


      ## Browserless.saveProfile


      Captures the browser's current state (cookies, localStorage, IndexedDB)
      and saves it as a named profile. Reuse the profile on future sessions via
      the `?profile=<name>` query parameter.


      Call via CDP: `cdp.send('Browserless.saveProfile', { name: 'my-login' })`


      Returns: `{ profileId: '...', name: 'my-login' }`


      | Parameter | Type | Description |

      |---|---|---|

      | `name` | `string` | Profile name for retrieval on future sessions. |


      ## Browserless.refreshProfile


      Overwrites an existing profile's saved state with the current browser
      state. Useful for rotating session tokens without creating a new profile.


      Call via CDP: `cdp.send('Browserless.refreshProfile')`


      ## Browserless.pageIdentifier


      Returns a stable identifier for the current browser tab, useful for
      routing and session management.


      Call via CDP: `cdp.send('Browserless.pageIdentifier')`


      Returns: `{ id: '...' }`
    x-displayName: CDP Extensions
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
      - CDP Extensions
  - name: Chrome
    tags:
      - Chrome (licensed build)
