{ "customSiteTitle": "Browserless Documentation", "definitions": { "FrameAddScriptTagOptions": { "type": "object", "properties": { "url": { "description": "URL of the script to be added.", "type": "string" }, "path": { "description": "Path to a JavaScript file to be injected into the frame.", "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" }, "path": { "description": "The path to a CSS file to be injected into the frame.", "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\nAPI.", "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\nthe 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\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/definitions/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\nto the endpoint that set the cookie.\n\nIn 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\nthe topLevelSite.\n\nSupported 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\n{@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}.", "type": "string" }, "referrerPolicy": { "description": "If provided, it will take preference over the referer-policy header value\nset by {@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}.", "type": "string" }, "timeout": { "description": "Maximum wait time in milliseconds. Pass 0 to disable the timeout.\n\nThe default value can be changed by using the\n{@link Page.setDefaultTimeout} or {@link Page.setDefaultNavigationTimeout}\nmethods.", "type": "number" }, "waitUntil": { "description": "When to consider waiting succeeds. Given an array of event strings, waiting\nis considered to be successful after all events have been fired.", "anyOf": [ { "type": "array", "items": { "$ref": "#/definitions/PuppeteerLifeCycleEvent" } }, { "enum": [ "domcontentloaded", "load", "networkidle0", "networkidle2" ], "type": "string" } ] }, "signal": { "description": "A signal object that allows you to cancel the call.", "$ref": "#/definitions/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" ] }, "Record": { "type": "object", "additionalProperties": false }, "Protocol.Emulation.UserAgentMetadata": { "description": "Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints\nMissing 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": "#/definitions/Protocol.Emulation.UserAgentBrandVersion" } }, "fullVersionList": { "description": "Brands appearing in Sec-CH-UA-Full-Version-List.", "type": "array", "items": { "$ref": "#/definitions/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.\nSee 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.\nSee {@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" }, "env": { "description": "Environment for the browser process. Honored by both puppeteer.launch and\nplaywright.launchServer. Set server-side to give the session its own TMPDIR\n(see generateScratchDir); a caller-supplied value is merged under it, since\na session must not be able to point its scratch back at the shared temp dir.\n\nThat merge happens on the object handed to `launch` only. It is kept off\nthe session's stored `launchOptions`, which /sessions serves verbatim.", "$ref": "#/definitions/Record%3Cstring%2Cstring%7Cundefined%3E" }, "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" } } }, "Record": { "type": "object", "additionalProperties": false }, "JSONSchema": { "type": "object", "properties": { "code": { "type": "string" }, "context": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ContextValue" } } }, "additionalProperties": false, "required": [ "code" ] }, "ContextValue": { "anyOf": [ { "type": "array", "items": { "$ref": "#/definitions/ContextValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/definitions/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\nsession 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\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/definitions/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" }, "path": { "description": "The file path to save the image to. The screenshot type will be inferred\nfrom file extension. If path is a relative path, then it is resolved\nrelative to current working directory. If no path is provided, the image\nwon't be saved to the disk.", "type": "string" }, "clip": { "description": "Specifies the region of the page/element to clip.", "$ref": "#/definitions/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" ] }, "LiveURLCompleteReason": { "enum": [ "closed", "timeout", "userDone", "userFailed", "viewerDisconnected" ], "type": "string" }, "ProxyType": { "description": "The proxy networks the platform can route through. `residential` uses the\nbuilt-in residential vendors; `datacenter` uses the Geonode datacenter\nnetwork (cheaper, billed at a lower per-MB rate).", "enum": [ "datacenter", "residential" ], "type": "string" }, "Record": { "type": "object", "additionalProperties": false }, "CookieSameSite_2": { "description": "Represents the cookie's 'SameSite' status:\nhttps://tools.ietf.org/html/draft-west-first-party-cookies", "enum": [ "Default", "Lax", "None", "Strict" ], "type": "string" }, "CookiePriority": { "description": "Represents the cookie's 'Priority' status:\nhttps://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\n\"Unset\" allows protocol clients to emulate legacy cookie scope for the scheme.\nThis is a temporary ability and it will be removed in the future.", "enum": [ "NonSecure", "Secure", "Unset" ], "type": "string" }, "ScrapeGroupResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/ScrapeElementResult" } }, "selector": { "type": "string" } }, "additionalProperties": false, "required": [ "results", "selector" ] }, "ScrapeElementResult": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false, "required": [ "name", "value" ] } }, "height": { "type": "number" }, "html": { "type": "string" }, "left": { "type": "number" }, "text": { "type": "string" }, "top": { "type": "number" }, "width": { "type": "number" } }, "additionalProperties": false, "required": [ "attributes", "height", "html", "left", "text", "top", "width" ] }, "InboundResponse": { "type": "object", "properties": { "headers": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E" }, "status": { "type": "number" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "status", "url" ] }, "OutboundRequest": { "type": "object", "properties": { "headers": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E" }, "method": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "method", "url" ] }, "Platform": { "enum": [ "android", "linux", "macos", "windows" ], "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" }, "ImageFormat": { "enum": [ "jpeg", "png", "webp" ], "type": "string" }, "SearchResponseData": { "type": "object", "properties": { "web": { "type": "array", "items": { "$ref": "#/definitions/WebSearchResult" } }, "news": { "type": "array", "items": { "$ref": "#/definitions/NewsSearchResult" } }, "images": { "type": "array", "items": { "$ref": "#/definitions/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 }, "SearchFailureCode": { "enum": [ "no_results", "upstream_timeout", "upstream_unavailable" ], "type": "string" }, "UnresponsiveEngine": { "type": "object", "properties": { "engine": { "type": "string" }, "reason": { "$ref": "#/definitions/UnresponsiveEngineReason" } }, "additionalProperties": false, "required": [ "engine", "reason" ] }, "UnresponsiveEngineReason": { "enum": [ "access_denied", "captcha", "rate_limited", "timeout", "unknown" ], "type": "string" }, "Record": { "type": "object", "additionalProperties": false }, "CrawlStatus": { "enum": [ "cancelled", "completed", "failed", "in-progress" ], "type": "string" }, "CrawlPageResponse": { "type": "object", "properties": { "status": { "$ref": "#/definitions/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": "#/definitions/CrawlStatus" }, "total": { "type": "number" }, "completed": { "type": "number" }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" } }, "additionalProperties": false, "required": [ "completed", "completedAt", "createdAt", "id", "status", "total", "url" ] }, "SkillResponse": { "description": "The public shape: no `source`, which carries token_hash / sessionId.", "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "task": { "type": "string" }, "title": { "type": "string" }, "skill_md": { "type": "string" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false, "required": [ "created_at", "domain", "id", "skill_md", "task", "title", "updated_at", "version" ] }, "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/definitions/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "type": "string" }, "ProfileCookie": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "string" }, "expires": { "type": "number" }, "size": { "type": "number" }, "httpOnly": { "type": "boolean" }, "secure": { "type": "boolean" }, "session": { "type": "boolean" }, "sameSite": { "enum": [ "Lax", "None", "Strict" ], "type": "string" }, "sourceScheme": { "enum": [ "NonSecure", "Secure", "Unset" ], "type": "string" }, "sourcePort": { "type": "number" } }, "additionalProperties": false, "required": [ "domain", "expires", "httpOnly", "name", "path", "secure", "session", "size", "value" ] }, "DownloadProfileOriginStorage": { "type": "object", "properties": { "origin": { "type": "string" }, "localStorage": { "$ref": "#/definitions/DownloadProfileLocalStorage" }, "indexedDBs": { "type": "array", "items": { "$ref": "#/definitions/DownloadProfileIndexedDB" } } }, "additionalProperties": false, "required": [ "localStorage", "origin" ] }, "DownloadProfileLocalStorage": { "type": "object", "additionalProperties": { "type": "string" } }, "DownloadProfileIndexedDB": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "number" }, "objectStores": { "type": "array", "items": { "$ref": "#/definitions/DownloadProfileIndexedDBObjectStore" } } }, "additionalProperties": false, "required": [ "name", "objectStores", "version" ] }, "DownloadProfileIndexedDBObjectStore": { "type": "object", "properties": { "name": { "type": "string" }, "keyPath": { "anyOf": [ { "$ref": "#/definitions/DownloadProfileNullableKeyPath" }, { "type": "null" } ] }, "autoIncrement": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/ProfileIndexedDBEntry" } }, "indexes": { "type": "array", "items": { "$ref": "#/definitions/DownloadProfileIndexedDBIndex" } } }, "additionalProperties": false, "required": [ "autoIncrement", "entries", "indexes", "keyPath", "name" ] }, "DownloadProfileNullableKeyPath": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "ProfileIndexedDBEntry": { "type": "object", "properties": { "key": {}, "value": {} }, "additionalProperties": false, "required": [ "key", "value" ] }, "DownloadProfileIndexedDBIndex": { "type": "object", "properties": { "name": { "type": "string" }, "keyPath": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "unique": { "type": "boolean" }, "multiEntry": { "type": "boolean" } }, "additionalProperties": false, "required": [ "keyPath", "multiEntry", "name", "unique" ] }, "ProfileResponse": { "description": "Public-facing profile response returned by HTTP routes.\nOmits 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" }, "captureSettings": { "$ref": "#/definitions/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/definitions/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ] }, "RefreshCaptureSettingsPayload": { "description": "Declared locally, not imported, so the generator emits a flat definition —\nmust stay field-for-field equal to `ProfileCaptureSettings` in\n`../../profiles/types.ts`. `profile.http.spec.ts` pins it two ways: an\n`Exact<>` type assertion, and a key-set check against the generated\n`*.body.json` — the artifact that actually decides whether a request 400s.\nAll-optional so a partial payload cannot 400, and non-nullable because the\ngenerator drops the null. Nested definitions get\n`additionalProperties: false`, so **adding a member here is an\nenterprise-first deploy, every time.**", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value.", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list, not just the `--exclude-domain` flags.", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings.", "type": "string" } }, "additionalProperties": false }, "RefreshResponseDiagnostics": { "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped 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" }, "skippedMalformedLocalStorageEntries": { "description": "localStorage entries dropped because names or values were not strings.", "type": "number" }, "skippedMalformedIdbIndexes": { "description": "IndexedDB indexes dropped because required fields were malformed.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbIndexes", "skippedMalformedIdbStores", "skippedMalformedLocalStorageEntries", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] }, "UploadCaptureSettingsPayload": { "description": "Declared locally, not imported, so the generator emits a flat definition —\nmust stay field-for-field equal to `ProfileCaptureSettings` in\n`../../profiles/types.ts`. `profile.http.spec.ts` pins it two ways: an\n`Exact<>` type assertion, and a key-set check against the generated\n`*.body.json` — the artifact that actually decides whether a request 400s.\nAll-optional so a partial payload cannot 400, and non-nullable because the\ngenerator drops the null. Nested definitions get\n`additionalProperties: false`, so **adding a member here is an\nenterprise-first deploy, every time.**", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value.", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list, not just the `--exclude-domain` flags.", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings.", "type": "string" } }, "additionalProperties": false }, "UploadResponseDiagnostics": { "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped 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" }, "skippedMalformedLocalStorageEntries": { "description": "localStorage entries dropped because names or values were not strings.", "type": "number" }, "skippedMalformedIdbIndexes": { "description": "IndexedDB indexes dropped because required fields were malformed.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbIndexes", "skippedMalformedIdbStores", "skippedMalformedLocalStorageEntries", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] }, "OpAuditLogResponse": { "description": "Public-facing audit-log entry returned by the audit HTTP route. Omits\ntoken_hash — never includes any token material — and carries the credential\nreference plus non-secret target metadata only.", "type": "object", "properties": { "id": { "description": "Unique audit-entry identifier.", "type": "string" }, "integrationId": { "description": "Integration this credential operation used.", "type": "string" }, "profileId": { "description": "Authentication profile associated with the operation, 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": "#/definitions/OpAuditOutcome", "description": "`success` if filled, `saved` if created, otherwise `failure`." }, "errorCode": { "description": "Error code when the outcome is `failure`, otherwise null.", "type": "string" }, "createdAt": { "description": "ISO timestamp of the operation.", "type": "string" } }, "additionalProperties": false, "required": [ "createdAt", "errorCode", "id", "integrationId", "outcome", "profileId", "secretRef", "targetDescriptor", "targetOrigin", "targetSelector" ] }, "OpAuditOutcome": { "description": "Outcome recorded for a Browserless.loadSecret or saveSecret attempt.", "enum": [ "failure", "saved", "success" ], "type": "string" }, "OpIntegrationKind": { "enum": [ "connect", "service_account" ], "type": "string" }, "OpIntegrationResponse": { "description": "Public-facing integration response returned by HTTP routes.\nOmits internal fields — never includes token_hash or any token material.", "type": "object", "properties": { "vaults": { "description": "Live vault titles, only with includeVaults=true; null when unavailable.", "type": "array", "items": { "type": "string" } }, "id": { "description": "Unique integration identifier.", "type": "string" }, "label": { "description": "User-supplied label. Unique per token.", "type": "string" }, "kind": { "$ref": "#/definitions/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" ] }, "InboxCandidate": { "type": "object", "properties": { "vault": { "type": "string" }, "item": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false, "required": [ "item", "label", "vault" ] }, "AutologinState": { "description": "Lifecycle state of an autologin task.", "enum": [ "failed", "pending", "running", "success" ], "type": "string" }, "AutologinDomainResult": { "type": "object", "properties": { "origin": { "type": "string" }, "status": { "$ref": "#/definitions/AutologinDomainStatus" }, "error": { "type": "string" }, "errorCode": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": false, "required": [ "origin", "status" ] }, "AutologinDomainStatus": { "description": "Per-origin progress/outcome as the agent works through the domain list.\nLive: `pending` (not reached), `active` (currently attempting), `tried`\n(moved past — outcome not yet known). Terminal: `success` | `failed`.", "enum": [ "active", "failed", "pending", "success", "tried" ], "type": "string" } }, "info": { "title": "Browserless", "version": "2.57.0", "x-logo": { "altText": "browserless logo", "url": "./browserless-logo-inline.svg" }, "description": "# Browserless.io\n\nThis service extends the Browserless open-source image with many features and enhancements for teams automating at scale. Notable features include:\n\n- A Chrome-devtools-protocol based API for extending and enhancing libraries in a cross-language way.\n- A new hybrid-automation toolkit with live session interactivity.\n- Robust session management: connect, reconnect, kill and limit what a browser can do.\n- Bleeding features like multiplexing numerous clients into a single Chrome process in an isolated way.\n- The ability to upload and run custom extensions.\n- Run multiple tokens, with access controls on each.\n- Multi-browser with all the robust capabilities already in the open-source images.\n\nThere's a lot to cover here so let's get started!\n\n## Browser ownership configuration\n\n| Environment variable | Default (enterprise image) | Description |\n| --------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `ENFORCE_BROWSER_OWNERSHIP` | `false` | Set exactly `true` to enforce per-owner access for reconnects, on-demand live URLs, and browser termination. Applies to self-hosted and dedicated deployments, with or without Redis. Hosted cloud always enforces ownership and ignores this variable. |\n\nSelf-hosted tokens represent roles within one deployment, rather than separate\ntenants. By default, authenticated callers can access browsers across tokens;\nadding Redis does not change that policy. Existing route authentication, role\npermissions, and explicit reconnect `auth` secrets remain enforced. Opting in\ncan reject requests when ownership metadata is unavailable, including raw-ID\nreconnects without Redis.\n\n## Skill catalog telemetry\n\n`GET /skills` preserves existing successful `Skill Lookup` hit/miss counts.\nStore failures emit structured internal `event.name=skill.lookup.failed`\nERROR logs through `EnterpriseLogger` and its existing Winston/OTLP transport:\n`store_unavailable` at stage `store` (HTTP 503), or `store_error` at stage\n`lookup` (the original store exception is rethrown). Fields include normalized\ndomain (at most 253 characters), an optional safe task slug (at most 100\ncharacters), `duration_ms`, and `request_id`. A UUID `x-request-id` from MCP\ncorrelates both sides; otherwise the server request ID is used, or a UUID is\ngenerated. No raw exception, URL, query, token, recipe, or prompt is added.\n\nCaught `Skill Lookup` delivery failures emit\n`skill.telemetry.delivery_failed` WARN with `originating_event=Skill Lookup`\nand fixed diagnostic `error_category=delivery_error`, at most once per minute\nper process. Diagnostics never retry through the failing analytics queue.\nThese records are internal, not customer-log events. Export still requires\nthe existing `OTEL_ENABLED`, `OTEL_LOGS_ENABLED`, and collector configuration.\n\nExample attributes: `{\"event.name\":\"skill.lookup.failed\",\"request_id\":\"416e0409-25e2-4399-a3fa-6939f43a75e0\",\"domain\":\"shop.example\",\"task\":\"search\",\"stage\":\"lookup\",\"error_category\":\"store_error\",\"duration_ms\":17}`.\nKeep this server view separate from MCP `Skill Retrieval Completed`: retrieval\nerror rate = error/all completions, and hit rate = hit/valid completions.\nLocal mock tests verify construction and isolation, not deployed receipt.\n\n# Software Keys\n\nThe Enterprise image supports time-limited software keys that allow usage for a specific period without requiring any external connections or callbacks. These keys are cryptographically secure and cannot be reverse engineered. When a key expires, the container will exit with a semantic error code.\n\n## Using a Software Key\n\nTo use a software key, set the `KEY` environment variable when running the container:\n\n```bash\ndocker run -e KEY=your-generated-key browserless/enterprise\n```\n\n# Using the Browserless Proxy\n\n> The Residential proxy is only available for Enterprise and Cloud plans.\n\nBrowserless comes with a built-in mechanism to proxy to what's called \"residential\" IPs. These are IP addresses are sourced from real-users running a proxy server on their home networking machines. Residential proxying is especially useful for things like bypassing certain bot blockages and more.\n\nUsing a residential proxy is as straightforward as adding a few parameters to your library or API calls. Here's the required parameters and the values they support:\n\n- `?proxy=residential`: Specifies that you want to use the residential proxy for this request.\n- `?proxy=datacenter`: Use the datacenter proxy pool instead of residential. Cheaper (2 units/MB vs 6) but more easily detected; country/state/city/sticky targeting works the same.\n- `?proxyCountry=us`: Specifies a country you wish to use for the request. A two-digit ISO code.\n- `?proxySticky=true`: If you want to use the same IP address for the entirety of the session. Generally recommended for most cases.\n- `?proxyPreset=px_gov01`: Website-specific proxy configuration. Use `px_gov01` for government websites to ensure optimal proxy vendor selection.\n\nSimply append these to your connection call, REST API calls, or any library call:\n\n`wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&proxy=residential&proxyCountry=us&proxySticky`\n\n`https://production-sfo.browserless.io/chromium/unblock?token=YOUR-API-TOKEN&proxy=residential&proxyCountry=us&proxySticky`\n\nPlease do note that using a proxy will increase the amount of units consumed. Every megabyte of data transferred consumes 6 units for residential, or 2 units for datacenter.\n\n# The Browserless CDP API\n\nIn order to enhance the experience with open source libraries like Puppeteer, we decided to take a new approach to extending these libraries in a language-agnostic way. We call it the Browserless CDP API. Here's a quick list of what it can do:\n\n- Generate and give back live URLs for hybrid automation.\n- Solve Captchas.\n- Return your page's unique identifier created by Chrome.\n- Way more coming!\n\nSince most libraries come with a way to issue \"raw\" CDP commands, it's an easy way to drop-in custom behaviors without having to write and maintain a library. Plus you can continue to enjoy using the same packages you've already come to know.\n\nGetting started with this API is pretty simple. For instance, if you want to use the live viewer for a particular page, simply do the following:\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n const { liveURL } = await cdp.send('Browserless.liveURL');\n\n // liveURL = 'http://localhost:5555/live/?i=98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\nYou can then visit this URL in any browser to interact with the headless Chrome running someplace else.\n\nSee more below for a full list of the available APIs and features.\n\n## Browserless.liveURL\n\nReturns a fully-qualified URL to load into a web-browser. This URL allows for clicking, typing and other interactions with the underlying page. This URL doesn't require an authorization token, so you're free to share it externally with your own users or employees. If security is a concern, you can set a `timeout` parameter to limit the amount of time this URL is valid for. By default no `timeout` is set and the URL is good as long as the underlying browser is open.\n\nProgrammatic control of the session is also available, so you can close the live session once your code has detected a selector, network call, or whatever else. See the below example for programmatic control.\n\n**How the viewer works internally**\n\nThe live URL viewer is a Preact application in [`src/shared/utils/live-client/`](src/shared/utils/live-client/). It connects to [`live.server.ts`](src/shared/utils/live.server.ts) over WebSocket, receives browser screenshots as binary frames, and draws them directly onto a stable canvas. Preact manages the tabs, navigation controls and overlays; image frames bypass component state. Keyboard, pointer and clipboard events travel back over the same connection for the server to apply to the remote browser.\n\nRun `npm run build:client` after editing the viewer. [`scripts/build-client.js`](scripts/build-client.js) bundles its TypeScript/TSX and CSS with esbuild into `static/live/client.js` and `static/live/client.css`, loaded by [`static/live/index.html`](static/live/index.html). Preact is a build-time dev dependency bundled into the client.\n\n**Basic example**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n const { liveURL } = await cdp.send('Browserless.liveURL');\n\n // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\n**Timeout example**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n const { liveURL } = await cdp.send('Browserless.liveURL', {\n timeout: 10000, // 10 seconds to connect!\n });\n\n // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\n**Maintaining the width and height**\n\nBy default, Browserless will dynamically change the width and height of the browser to match an end-users screen. This isn't always ideal and can be disabled by setting a `resizable` value to `false`. When this is done, only your script can alter the width and height of the browser:\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n\n // Width and height will always be 1920x1080\n // and the Live URL will maintain this aspect ratio\n await page.setViewport({ width: 1920, height: 1080 });\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n const { liveURL } = await cdp.send('Browserless.liveURL', {\n resizable: false,\n });\n\n // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\n**Setting a Quality and Type**\n\n`quality` and `type` control image compression, not the stream's pixel dimensions. Defaults are `quality: 70` and `type: 'jpeg'`. Higher JPEG quality reduces compression artifacts but can increase bandwidth and latency. Use `type: 'png'` for lossless frames; `quality` only applies to JPEG.\n\n**Retina / high-DPI displays:** Set `captureScale: 2` to encode twice as many pixels on each axis without doubling the CSS layout. For example, a 400 × 700 CSS viewport produces 800 × 1400 frames:\n\n```js\nawait page.setViewport({ width: 400, height: 700 });\nconst cdp = await page.createCDPSession();\nconst { liveURL } = await cdp.send('Browserless.liveURL', {\n captureScale: 2,\n resizable: false,\n type: 'png',\n});\n```\n\nBQL supports the same option: `liveURL(captureScale: 2, resizable: false, type: png, quality: 100) { liveURL }` after `viewport(width: 400, height: 700)`.\n\n- `captureScale` accepts only `1` or `2`; omitted values default to `1`. Explicit `null`, strings, fractions, and `3` are rejected. It is independent of the viewer's device pixel ratio and of screenshot `deviceScaleFactor`.\n- `resizable: false` preserves the page's CSS dimensions. With `resizable: true`, viewer resizing changes the CSS viewport and the stream remains 2× that viewport.\n- 2× capture processes four times as many pixels. PNG preserves fine text but can increase bandwidth and encoding cost; JPEG quality remains an independent compression setting. A 3× display still receives a 2× stream, not a 3× stream.\n- At 2×, CSS dimensions must be positive integers, at most 4096 per side and 4,194,304 pixels total. Oversized viewer resizes are rejected and close that viewer.\n- Simultaneous viewers of the same page must use the same capture scale. Viewers share the page's viewport; resizing one changes the shared page. Re-minting a LiveURL for an existing page replaces its previous configuration and closes its current viewers.\n- Screenshots through Browserless CDP or BQL temporarily pause streaming and retain the screenshot caller's own DPR/clip/full-page settings. Direct connections to Chromium bypass that coordination. Do not combine 2× LiveURL with an explicit CDP `viewport` magnification or a non-default top-level emulation `scale`; these settings conflict and are rejected while the viewer is active.\n\nIncreasing JPEG quality, changing screen/window size, or enlarging the viewer's canvas alone does not add backing pixels. Increasing the page viewport to 800 × 1400 changes its CSS layout and is not equivalent to Retina rendering.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n const { liveURL } = await cdp.send('Browserless.liveURL', {\n quality: 70, // Can be 1 - 100. Default is 70\n type: 'jpeg', // Can be 'jpeg' or 'png'. Default is 'jpeg'\n compressed: true, // Whether to compress each frame of the streamed image data\n });\n\n // liveURL = 'https://production-sfo.browserless.io/live/?i=98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\n### Optional page inspector\n\nCDP callers can opt in to an embedded DevTools panel:\n\n```js\nconst { liveURL } = await cdp.send('Browserless.liveURL', {\n enableDevtools: true,\n interactable: true,\n showBrowserInterface: true,\n});\n```\n\nThis is a **trusted-operator debugging capability**, not a read-only viewer.\nElements and Console can modify the inspected page, and Network can expose its\nrequest/response data. Share the link only with operators who may access and\nmodify that page. `interactable: false` suppresses the control and rejects\ninspector connections even when `enableDevtools` is set. The option defaults to\nfalse and is currently exposed through `Browserless.liveURL` on CDP only.\n\nEach inspector connection is pinned to the selected page in the minted page's\nbrowser context. Switching tabs reloads the inspector; it does not grant the\nold connection access to another target. The server permits an explicit set of\npage-scoped Elements, Console and Network commands, not arbitrary CDP. Target\ndiscovery/attachment (including workers and out-of-process frames), browser or\ncontext administration, cookie-store access, host-file access, and unlisted\nadvanced DevTools operations are unavailable. Some native DevTools panels may\ntherefore report unsupported commands. This is not a replacement for a fully\nauthenticated debugger connection.\n\nAuthorization is checked for every command and response/event. Replacing or\ndeleting the mint, losing the last eligible live viewer, disabling interaction,\nor filling a managed secret prevents further inspector traffic. The existing\nsecret-fill teardown also closes inspectors already connected. Closing an\ninspector does **not** undo page changes or JavaScript an operator already ran;\ndo not use this mode to grant untrusted users access before a credential fill.\nInspector sockets consume the existing per-link connection limit but do not\ncreate a second LiveURL completion owner: the existing per-mint completion and\nviewer-reload grace behavior is unchanged.\n\nIt's also helpful to \"wait\" until the user is done doing what's needed. For that reason, Browserless will fire a custom event when the page is closed as well:\n\n**Wait for close**\n\n> Custom CDP Events are not supported in all libraries, including .NET Playwright.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n const { liveURL } = await cdp.send('Browserless.liveURL');\n\n console.log(liveURL);\n\n // Wait for the Browserless.liveComplete event when the live page is closed.\n // Please not that not all libraries support custom CDP events.\n await new Promise((r) => cdp.on('Browserless.liveComplete', r));\n\n console.log('Done!');\n\n await browser.close();\n})();\n```\n\n### Browserless.switchTab\n\nSend `Browserless.switchTab({ targetId })` from a page-scoped CDP session to\nsteer every connected Live URL viewer anchored to that page in the same browser.\nRegister `Browserless.liveViewerConnected` before opening the viewer and wait for\nit: each viewer emits this event once, after `startComplete`, when steering is\nready. Calls without a matching viewer fail immediately and are never queued.\n\nThe result is exactly `{ error: null, targetId: string }` on success or\n`{ error: string }` on failure (never a `targetId` on failure). These are CDP\nresult payloads, not protocol errors:\n\n| Condition | `error` |\n| ------------------------------------------------ | -------------------------------------------------------------------------- |\n| Missing, non-string, blank, or whitespace target | `The \"targetId\" parameter is required.` |\n| Caller session not mapped to a page | `Could not determine the caller target page.` |\n| No matching viewer | `No connected Live URL viewer is anchored to the caller target.` |\n| Target absent from any matching viewer | `The requested target is not available in every matching Live URL viewer.` |\n| Any switch fails after validation | `Failed to switch every matching Live URL viewer.` |\n\nAll matching viewers are validated before any switches. Success waits for every\nviewer to complete the switch and send its active-tab state. If a viewer closes\nor fails during switching, already-completed viewers are not rolled back.\nViewers anchored to other pages are unchanged.\n\nClosing the minting page no longer ends a viable Live URL. Its existing ID and\nviewers adopt the lexicographically smallest remaining tracked target, preserving\nthe URL, metadata, and original expiry. Reopening the same URL reconnects to that\nsurvivor. Failed adopters close individually; closing the final tracked page\nsends `browserClose`, deletes the ID, and immediately prevents reconnecting.\n\nThis method is available on `/chromium`, `/chromium/stealth`, `/chrome`, and\n`/chrome/stealth`. Native `Target.activateTarget` and `Page.bringToFront` do not\nsteer the Live URL. To close a tab, use native\n[`Target.closeTarget`](https://chromedevtools.github.io/devtools-protocol/tot/Target/#method-closeTarget),\nnot a `Browserless.closeTab` method.\n\n**Programmatic Control**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n // Having the liveURLId is required in order to close it later\n const { liveURL, liveURLId } = await cdp.send('Browserless.liveURL');\n\n await page.waitForSelector('.my-selector');\n\n // Calling this CDP API with the \"liveURLId\" will close the session, and terminate the client\n // further usage of the liveURL will fail and no more human-control is possible\n await cdp.send('Browserless.closeLiveURL', { liveURLId });\n\n // Continue to process or interact with the browser, then:\n await browser.close();\n})();\n```\n\nIt's recommended that you double check the page prior to executing further code to make sure the page is where it should be, elements are present, and so forth. This approach makes it easy to solve hard things like second-factor authentication and more in a trivial fashion.\n\n**Read-only LiveURL Sessions**\n\nThe `interactive: false` option allows you to create read-only LiveURL sessions where users can view the browser but cannot interact with it. This is useful for monitoring or demonstration purposes without allowing user input.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n // Create a read-only LiveURL session that users can view but not interact with\n const { liveURL } = await cdp.send('Browserless.liveURL', {\n interactive: false,\n });\n\n console.log('Read-only LiveURL:', liveURL);\n\n await browser.close();\n})();\n```\n\n## Browserless.reconnect\n\n> This API is only available for Enterprise plans. [Contact us for more information here.](https://www.browserless.io/contact/)\n\nReconnecting allows for the underlying Chrome or Chromium process to continue to run for a specified amount of time, and subsequent reconnecting back to it. With this approach you can also \"share\" this connection URL to other clients to connect to the same browser process, allowing you to parallelize via a single Browser process.\n\nOnce a reconnection URL is retrieved, Browserless will intercept close-based commands and stop them from terminating the browser process itself. This prevents clients from accidentally closing the process via `browser.close` or similar.\n\nIn order to use this API, simply call `Browserless.reconnect` as a CDP command. You can, optionally, set a `timeout` or an `auth` property. See the below examples for details\n\n**Basic example with timeout**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n // Allow this browser to run for 10 seconds, then shut down if nothing connects to it.\n // Defaults to the overall timeout set on the instance, which is 5 minutes if not specified.\n const { error, browserWSEndpoint } = await cdp.send('Browserless.reconnect', {\n timeout: 10000,\n });\n\n if (error) throw error;\n\n await browser.close();\n\n // browserWSEndpoint = 'https://production-sfo.browserless.io/reconnect/98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\nIf you want to enforce authentication, you can pass in an optional `auth` property that clients will need to use in order to connect with. Similar to how authentication works in general, a `token` query-string parameter will need to be applied.\n\n**Authentication example**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint =\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n // Set a custom authentication token that clients have to use in order to connect, or otherwise\n // receive a 401 Response.\n const { error, browserWSEndpoint } = await cdp.send('Browserless.reconnect', {\n auth: 'secret-auth-token',\n });\n\n if (error) throw error;\n\n await browser.close();\n\n // NOTE the URL here doesn't include the auth token!\n // browserWSEndpoint = 'https://production-sfo.browserless.io/reconnect/98e83bbfd396241a6963425b1feeba2f';\n})();\n```\n\n**Recursive Example**\n\n```js\nimport puppeteer from 'puppeteer-core';\n\nconst job = async (reconnectURL) => {\n const browserWSEndpoint =\n reconnectURL ??\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const [page] = await browser.page();\n const cdp = await page.createCDPSession();\n await page.goto('https://example.com');\n\n // Anytime Browserless.reconnect is called, this restarts the timer back to the provided value,\n // effectively \"bumping\" the timer forward.\n const res = await cdp.send('Browserless.reconnect', {\n timeout: 30000,\n });\n\n if (res.error) throw error;\n\n await browser.close();\n\n // Continuously reconnect back...\n return job(res.browserWSEndpoint);\n};\n\njob().catch((e) => console.error(e));\n```\n\n## Browserless.solveCaptcha\n\n> This API is only available for Enterprise and Scale and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). Only the `/chrome` and `/chromium` routes support Captcha solving.\n\nBrowserless comes with built-in captcha solving capabilities. We use a variety of techniques to try and mitigate the chances of captchas coming up, but if you happen to run into one you can simply call on our API to solve it.\n\nGiven the amount of possibilities during a captcha solve, the API returns many properties and information in order to help your script be more informed as to what happened. See the below code example for all details and fields returned by the API.\n\nPlease be aware that solving a captcha can take a few seconds up to several minutes, so you'll want to increase your timeouts accordingly for your scripts. Captcha's solved, or attempted to solve, cost 10 units.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browser = await puppeteer.connect({\n browserWSEndpoint:\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&timeout=300000',\n });\n\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n await page.goto('https://www.google.com/recaptcha/api2/demo', {\n waitUntil: 'networkidle0',\n });\n\n const {\n // A simple boolean indicating whether the script can proceed\n ok,\n // Whether or not a captcha was found\n captchaFound,\n // A human-readable description of what occurred.\n message,\n // Whether a solve was attempted or not\n solveAttempted,\n // If the Captcha was solved, only true if found AND solved\n solved,\n } = await cdp.send('Browserless.solveCaptcha', {\n // How long to wait for a Captcha to appear to solve.\n // Defaults to 10,000ms, or 10 seconds.\n appearTimeout: 30000,\n });\n\n console.log(message);\n\n if (ok) {\n await page.click('#recaptcha-demo-submit');\n } else {\n console.error(`Error solving captcha!`);\n }\n\n await browser.close();\n})().catch((e) => {\n console.error(e);\n process.exit(1);\n});\n```\n\nIn general, if an `ok` response is sent back from this API, then your script is good to proceed with further actions. If a captcha is to suddenly appears after an action then you might want to listen for the `Browserless.foundCaptcha` event (see below) and retry solving.\n\n## Browserless.foundCaptcha\n\n> This API is only available for Enterprise and Scale and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). Only the `/chrome` and `/chromium` routes support Captcha solving.\n\n> Custom CDP Events are not supported in all libraries, including .NET Playwright.\n\nEmitted whenever a captcha widget is found on the page. Useful for checking if there's a captcha and deciding whether or not to proceed with solving.\n\nThe example below stops until a captcha is found, which may or may not be the case with every website out there.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n// Recaptcha\n(async () => {\n const browser = await puppeteer.connect({\n browserWSEndpoint:\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&timeout=300000',\n });\n\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n\n await page.goto('https://www.google.com/recaptcha/api2/demo', {\n waitUntil: 'networkidle0',\n });\n\n // Please note that not all libraries support custom CDP events.\n await new Promise((resolve) =>\n cdp.on('Browserless.captchaFound', (params) => {\n console.log('Found a captcha!');\n return resolve();\n }),\n );\n\n const { solved, error } = await cdp.send('Browserless.solveCaptcha');\n console.log({\n solved,\n error,\n });\n\n // Continue...\n await page.click('#recaptcha-demo-submit');\n})().catch((e) => {\n console.error(e);\n process.exit(1);\n});\n```\n\n### Event Parameters\n\n| Parameter | Type | Description |\n| --------- | -------- | ---------------------------------------------- |\n| `type` | `string` | Captcha type (`recaptcha`, `cloudflare`, etc.) |\n| `status` | `string` | Status: `\"found\"` or `\"solving\"` |\n\n## Browserless.captchaAutoSolved\n\n> This API is only available for Enterprise and Scale and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/). Only the `/chrome` and `/chromium` routes support Captcha solving.\n\n> Custom CDP Events are not supported in all libraries, including .NET Playwright.\n\nEmitted whenever a captcha widget is solved in the page by the auto-solving feature. Note that this event is not emitted when a captcha is solved manually.\n\nTo enable this feature, you need to set the `solveCaptchas` option to `true` in your query parameters while connecting to the browser.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n// Helper function to wait for a captcha to be solved\nconst waitForCaptchaResolved = (cdp) => {\n return new Promise((resolve) => {\n const onCaptchaFound = (params) => {\n console.log('Captcha found, type:', params.type, params.status);\n cdp.on('Browserless.captchaAutoSolved', resolve);\n };\n\n cdp.on('Browserless.captchaFound', onCaptchaFound);\n });\n};\n\n// Recaptcha\n(async () => {\n const browser = await puppeteer.connect({\n browserWSEndpoint:\n 'wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN&solveCaptchas=true',\n });\n const page = await browser.newPage();\n const cdp = await page.target().createCDPSession();\n\n await page.goto('https://www.google.com/recaptcha/api2/demo', {\n waitUntil: 'networkidle0',\n });\n const captchaEvent = await waitForCaptchaResolved(cdp);\n console.log(captchaEvent);\n\n await browser.close();\n\n // Continue...\n await page.click('#recaptcha-demo-submit');\n})().catch((e) => {\n console.error(e);\n process.exit(1);\n});\n```\n\n### Event Parameters\n\n| Parameter | Type | Description |\n| ------------ | ---------------- | ------------------------------------------- |\n| `autoSolved` | `true` | Whether captcha was auto-solved |\n| `token` | `null \\| string` | Captcha token if solved |\n| `found` | `boolean` | Whether a captcha was found |\n| `solved` | `boolean` | Whether the captcha was successfully solved |\n| `time` | `number` | Time taken to solve (in milliseconds) |\n\n## Browserless.heartbeat\n\n> This API is only available for Enterprise hosted and Starter and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/).\n\n> Custom CDP Events are not supported in all libraries, including .NET Playwright.\n\nA custom event emitted every several seconds, signaling a live connection. This is useful for a few reasons:\n\n- It ensure that your connection with the browser is still good.\n- Sending data can trigger some load-balancing technologies to not kill the connection.\n\nToday this event is emitted every 30 seconds.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\nconst browserWSEndpoint = `wss://production-sfo.browserless.io/chromium?token=YOUR-API-TOKEN`;\n\n(async () => {\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n await page.goto('https://example.com/');\n const client = await page.createCDPSession();\n\n client.on('Browserless.heartbeat', () => {\n console.log('Browserless.heartbeat');\n });\n})();\n```\n\n## Browserless.pageId\n\n> This API is only available for Enterprise hosted and Starter and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/).\n\nA simple helper utility to return the page's unique ID. Since most libraries treat this ID as opaque, and some even hide it, knowing the page's ID can be of great help when interacting with other parts of Browserless.\n\n```js\nimport puppeteer from 'puppeteer-core';\n\n(async () => {\n const browserWSEndpoint = 'wss://production-sfo.browserless.io/chromium';\n const browser = await puppeteer.connect({ browserWSEndpoint });\n const page = await browser.newPage();\n const cdp = await page.createCDPSession();\n const { pageId } = await cdp.send('Browserless.pageId');\n\n // pageId = 'ABC12354AFDC123';\n})();\n```\n\nYou can, optionally, try and \"find\" this ID in puppeteer or similar libraries. Given that puppeteer has this property underscored, it's likely to change or be unavailable in the future, and requires the infamous `// @ts-ignore` comment to allow TypeScript compilation.\n\n```ts\nconst getPageId = (page: Page): string => {\n // @ts-ignore\n return page.target()._targetId;\n};\n```\n\n## Browserless.loadSecret\n\n> This API is only available for Enterprise hosted and Starter and above plans on Cloud. [Contact us for more information here.](https://www.browserless.io/contact/).\n\nResolves a credential server-side and types it into a page field without the value ever reaching your automation, script, or the response. It accepts either a 1Password `op://` reference (passwords, usernames, TOTP) or a `mail://` reference that reads a freshly-emailed one-time code over IMAP.\n\n```graphql\npassword: loadSecret(ref: \"op://Vault/Item/password\", selector: \"#password\") { ok error }\notp: loadSecret(ref: \"mail://Vault/Item/otp\", selector: \"#otp\") { ok error }\n```\n\n### Reading emailed one-time codes (`mail://`)\n\nSome logins email a 6-digit code as a second factor. `loadSecret` can fetch that code from a mailbox and type it in — the code is never exposed to the agent.\n\n**You provide an IMAP-compliant inbox.** Any provider that supports IMAP over implicit TLS (port 993) works (Gmail is supported and tested in v1). Use a **dedicated** inbox for automation, not a personal mailbox: the resolver reads the newest inbox message on each call.\n\nFor Gmail: enable 2-Step Verification, then create a 16-character **App Password** at `myaccount.google.com/apppasswords`. That app password — not your account password — is what the resolver uses.\n\n**Store the inbox credentials as a 1Password Login item** in the vault your integration's service account can read:\n\n| Field | Value |\n| ------------------- | ----------------------------------------------------------------- |\n| `username` | the inbox address, e.g. `otp-bot@gmail.com` |\n| `password` | the inbox app password (16 chars for Gmail) |\n| `host` _(optional)_ | IMAP host for a non-Gmail provider (defaults to `imap.gmail.com`) |\n| `port` _(optional)_ | IMAP port (defaults to `993`, implicit TLS) |\n\nScope the service account to **only** this vault — the app password is the blast radius.\n\n**Reference it** with `mail:////otp`, where ``/`` are the 1Password vault and item titles (spaces allowed). Options:\n\n- `?wait=` — how long to poll for the code, in ms (default `45000`, clamped `5000`–`120000`).\n- `?from=` — only accept a message whose sender contains this substring.\n- `?pattern=` — a custom extraction regex (first capture group wins); defaults to a keyword-adjacent 4–8 digit run.\n\n**Timing.** Only a message that arrives _after_ the call starts is used, so a stale code already in the inbox is never returned. Trigger the site's \"send code\" step, then call `loadSecret` promptly — it waits for the code. Open the session with a `?timeout=` **larger than** the `wait` window, or the session limiter closes the socket mid-poll. If no fresh code arrives in the window, `loadSecret` returns `error: \"OtpTimeout\"`.\n\n**After a fill, the page is locked.** Once any secret (`op://` or `mail://`) is filled in a session, screenshots, PDFs, live URLs, and page-content reads (`evaluate`, `html`, `text`, `querySelector`, `cookies`) are disabled for the rest of that session so the value cannot be read back. Do any content reads _before_ calling `loadSecret`.\n\n## Predefined scrapers\n\nWhen `SCRAPE_BUNDLE_DIR` points at a built `predefined-scrapers` artifact, the instance loads it in a worker thread and exposes:\n\n- `GET /scrapers` — the catalog of loaded scrapers (organisation slug, hostnames, APIs, cache TTLs, output schemas).\n- `POST /scrapers/{scraper}/{api}` — run one API with `{ \"url\"?, \"params\"? }`; the response is `{ ok, data, error }` (a request rejected by input validation before dispatch gets the SDK's plain 400 instead).\n\nDetails, error codes and lifecycle: [`docs/scrape-bundle-runtime.md`](docs/scrape-bundle-runtime.md). The bundle contract itself: [`docs/scrape-bundle-contract.md`](docs/scrape-bundle-contract.md).\n\n# Changelog\n
\n

Note that these changes are only for Browserless' cloud, Enterprise and self-hosted Enterprise deployments. For information on the open-source container please refer to this link.

\n
\n

Latest

\n
    \n
  • Dependency updates.
    • \n
\n

v2.166.0

\n
    \n
  • Dependency updates.
    • \n
  • Require a valid token for all DevTools page and browser connections, including on dedicated instances.
    • \n
  • Mask prefilled and cleared form field values in session recordings.
    • \n
  • Fix color corruption in downscaled images captured by screenshots and PDFs.
    • \n
  • Honor a defaultViewport set when creating a session via /session, with clear validation errors.
    • \n
\n

v2.165.0

\n
    \n
  • Dependency updates.
    • \n
  • Make the vault optional when saving secrets, choosing it automatically when only one is available.
    • \n
  • Add live URL completion events that tell you when and why a live session ended.
    • \n
  • Fix live URLs showing an empty instructions prompt and expiring slightly before the requested timeout.
    • \n
  • Return an error when stopping session recording fails, instead of reporting success.
    • \n
  • Fix connecting a wallet integration, which failed during its authorization step.
    • \n
\n

v2.164.0

\n
    \n
  • Dependency updates.
    • \n
  • Add REST endpoints to create, monitor, and cancel live session URLs.
    • \n
  • Accept integration labels anywhere an integration ID is expected.
    • \n
  • Improve skill generation by filtering test sessions and redacting sensitive data.
    • \n
  • Fix CAPTCHA solving on pages with multiple widgets.
    • \n
  • Return clearer error messages when PDF generation fails.
    • \n
  • Speed up proxied requests and drop a retired residential proxy provider.
    • \n
  • Fix intermittent navigation timeouts on pages that load quickly.
    • \n
\n

v2.163.1

\n
    \n
  • Dependency updates.
    • \n
  • Improve agent checkout reliability so card payments complete instead of filling card details without charging.
    • \n
  • Improve agent sessions with redacted snapshots after secret fills, more accurate clicks, and single-tab handoff live links.
    • \n
  • Mask card numbers, email addresses, and passwords typed into form fields in session replays.
    • \n
  • Verify account ownership before allowing connections to an existing browser session.
    • \n
  • Limit Session API live links, reconnect windows, and keep-alive to the session's expiry time.
    • \n
  • Stop charging proxy usage for sessions that fell back to a direct connection.
    • \n
\n

v2.163.0

\n
    \n
  • Dependency updates.
    • \n
  • Let /agent/run pause for human help, report missing recordings, and keep generated skills to visited sites.
    • \n
  • Restore the standard default viewport on /screenshot, /pdf, /content, and /export.
    • \n
  • Fix blockConsentModals request timeouts and cap /export wait times to the request timeout.
    • \n
  • Preserve proxy city targeting when reconnecting to a BrowserQL session.
    • \n
  • Redact credentials and request bodies from request logs.
    • \n
\n

v2.162.0

\n
    \n
  • Dependency updates.
    • \n
  • Add support for completing one-time payments for agents.
    • \n
  • Improve CAPTCHA solving.
    • \n
  • Bug fixes.
    • \n
\n

v2.161.0

\n
    \n
  • Dependency updates.
    • \n
  • Add optional final-page captures in multiple formats to managed agent runs.
    • \n
  • Add an optional DevTools panel to live sessions and improve live view resizing.
    • \n
  • Report a completion reason once per live URL, including links that are never opened.
    • \n
  • Improve CAPTCHA solving on checkout pages that render challenges immediately on load.
    • \n
\n

v2.160.0

\n
    \n
  • Dependency updates.
    • \n
  • Add opt-in recording for /agent/run sessions and limit live-view links to the session's remaining lifetime.
    • \n
  • Fix reconnecting to persistent sessions right after a client disconnects.
    • \n
  • Improve CAPTCHA solving for slider puzzles and press-and-hold challenges.
    • \n
  • Block sensitive host-level browser commands by default, with ALLOW_RESTRICTED_CDP_METHODS opt-in for self-hosted deployments.
    • \n
  • Reject invalid proxy state values with a clear error.
    • \n
  • Fix BrowserQL deep selectors acting on the wrong page and incomplete screenshots of tall elements.
    • \n
\n

v2.159.0

\n
    \n
  • Add optional task instructions to live sessions.
    • \n
  • Improve CAPTCHA solving reliability.
    • \n
  • Improve error messages returned to browser pages when a request is rejected.
    • \n
  • Fix browser launch flags with values being ignored when passed in launch.args.
    • \n
  • Fix browser reconnects on self-hosted deployments.
    • \n
  • Security hardening for outbound network requests.
    • \n
\n

v2.158.0

\n
    \n
  • Dependency updates.
    • \n
  • Add a closeLiveURL BQL mutation to close live URLs and disconnect their viewers.
    • \n
  • Improve CAPTCHA solving, including challenges inside embedded cross-origin frames, with fewer false-positive solve results.
    • \n
  • Add on-demand recovery of saved profiles through automated login.
    • \n
  • Show clearer errors when connecting credential integrations with invalid tokens.
    • \n
  • Fix corrupted screenshots of tall elements.
    • \n
  • Fix session recordings losing their final events when sessions close immediately after stopping.
    • \n
\n

v2.157.0

\n
    \n
  • Dependency updates.
    • \n
  • Smart Scrape can now run a sequence of page actions — waiting, clicking, typing, and scrolling — before extracting content, so you can reach content that only appears after interaction.
    • \n
  • Automated login now completes email one-time-code (OTP) verification when creating authenticated profiles, so sign-ins that email a code no longer stall.
    • \n
  • Improved CAPTCHA solving for slider challenges that run inside embedded frames, with more reliable solver selection.
    • \n
  • Search now tells genuinely empty results apart from sources that were unavailable or timed out, so retries happen only when they can help.
    • \n
  • Live URL sessions can now switch the viewer between browser tabs, and the Live URL stays valid when the original page closes.
    • \n
  • Improved proxy reliability — failed proxy providers recover on the next request.
    • \n
\n

v2.156.0

\n
    \n
  • Dependency updates.
    • \n
  • Allow removing selected sites and their stored browser state from saved profiles.
    • \n
  • Add agent-assisted checkout support for authenticated browser sessions.
    • \n
  • Add secure credential saving and clearer guidance after secret entry.
    • \n
  • Improve session replay privacy and prevent replay from stalling browser actions.
    • \n
  • Preserve protected-site session settings and solve details in generated scripts.
    • \n
  • Make strict network-idle waits settle sooner for intentionally long-lived connections.
    • \n
\n

v2.155.0

\n
    \n
  • Honor explicit networkidle0 waits so slow-loading pages fully finish before screenshots, with a bounded maximum extra wait.
    • \n
\n

v2.154.0

\n
    \n
  • Dependency updates.
    • \n
  • Fix intermittent CAPTCHA solve failures on pages that embed a standalone Turnstile widget.
    • \n
\n

v2.153.0

\n
    \n
  • Updated dependencies and improved runtime stability.
    • \n
  • Improved usage and performance monitoring across browser automation, scraping, and live sessions.
    • \n
  • Improved compatibility and reliability for CAPTCHA solving.
    • \n
  • Improved session recording and live viewer reliability.
    • \n
  • Added safeguards for background navigation and screenshot requests.
    • \n
\n

v2.152.0

\n
    \n
  • Dependency updates.
    • \n
  • Add optional task outcome reporting to the agent API, with verdicts shown in session completion logs.
    • \n
  • Add predefined scraper endpoints at /scrapers, enabled by setting SCRAPE_BUNDLE_DIR.
    • \n
  • Keep Windows device-profile assignment consistent for a session, including across reconnects.
    • \n
  • Fix BrowserQL network-idle waitUntil options so navigation waits for the page to finish loading.
    • \n
  • Improve Smart Scrape result quality by rejecting blocked or empty pages, and add an onlyMainContent option.
    • \n
\n

v2.151.0

\n
    \n
  • Add capability discovery for agent sessions to check supported features before a browser is allocated.
    • \n
  • Brave stealth sessions now identify as Brave instead of masking as Chrome, improving fingerprint consistency.
    • \n
\n

v2.150.0

\n
    \n
  • Dependency updates.
    • \n
  • Route a portion of agent runs and script generation to an alternate model configuration, keyed by account.
    • \n
  • Improve Akamai detection in captcha auto-detect, including site-branded deny pages.
    • \n
  • Fix PerimeterX solves reporting success before the page had actually loaded.
    • \n
  • Return the PerimeterX clearance token more reliably after a successful solve.
    • \n
  • Add DataDome interstitial solving to the /unblock endpoint.
    • \n
  • Fix captcha solves failing with a missing-proxy error on reused browser sessions.
    • \n
\n

v2.149.0

\n
    \n
  • Dependency updates.
    • \n
  • Add OS, screen, and device-scale persona options to Agent routes.
    • \n
  • Expose content-shaping controls on POST /smart-scrape, add rawText, and return page metadata.
    • \n
  • Improve stealth session fingerprinting.
    • \n
  • Block denied BrowserQL requests.
    • \n
  • Fix injected script and style tags.
    • \n
\n

v2.148.0

\n
    \n
  • Dependency updates.
    • \n
  • The /pdf endpoint now uses the request's granted timeout budget instead of a fixed limit.
    • \n
  • Hosted Cloud sessions created without an expiry are now bounded by the plan's retention limit.
    • \n
  • Fix residential proxy connections to fidelity.com failing to load.
    • \n
\n

v2.147.1

\n
    \n
  • Dependency updates.
    • \n
  • Allow /screenshot captures to run for the full request timeout instead of stopping at 30 seconds.
    • \n
  • Fix /export returning the wrong document when a page navigates away or rewrites itself during waits.
    • \n
  • Block requests to disallowed URLs without ending the whole session over benign sub-resources.
    • \n
  • Improve captcha solving in stealth sessions by matching each persona's screen size and touch behavior.
    • \n
  • Make the spoofed GPU and browser identity consistent between pages and workers in stealth sessions.
    • \n
\n

v2.147.0

\n
    \n
  • Dependency updates.
    • \n
  • Add session-end reporting for /chromium/agent sessions, including why a session timed out and how many commands ran.
    • \n
  • Fix clearSecrets in agent sessions not restoring screenshots, PDFs, and page captures after a secret-based login.
    • \n
  • Tighten reconnect authentication so tokenless reconnects are only allowed when no credentials or ownership are present.
    • \n
  • Fix deep crawls marking pages as failed when they have long titles, descriptions, or URLs.
    • \n
\n

v2.146.0

\n
    \n
  • Add a /profile/:name/download endpoint to export saved authentication profiles (cloud only).
    • \n
  • Allow self-hosted deployments to reconnect to browser sessions without a token when ownership cannot be determined.
    • \n
\n

v2.145.0

\n
    \n
  • Add session recording to the MCP agent, with start and stop controls.
    • \n
  • Add device, screen, and operating system emulation options to the MCP agent.
    • \n
  • Crawl results now expire according to your plan's retention period and are cleaned up automatically.
    • \n
  • Remove stale bot-protection cookies when restoring saved profiles, while preserving login cookies.
    • \n
  • The /meta endpoint now reports the Enterprise version, with the SDK version available separately.
    • \n
\n

v2.144.0

\n
    \n
  • Add an opt-in CAPTCHA_FAST_IDENTIFY setting that skips detection polling for explicitly specified captcha types, cutting solve latency.
    • \n
  • Add an opt-in CAPTCHA_SOLVE_TIMING setting that reports additional captcha solve timing metrics.
    • \n
  • Honor caller-supplied timeouts above 30 seconds on /pdf, /screenshot, and /content, up to the request's allowed time.
    • \n
  • Treat a timeout of 0 on /pdf, /screenshot, and /content as the request's full allowed time.
    • \n
\n

v2.143.1

\n
    \n
  • Dependency updates.
    • \n
  • Fix /pdf, /screenshot, /export, and /content requests failing when injected JavaScript contains escaped characters.
    • \n
\n

v2.143.0

\n
    \n
  • Dependency updates.
    • \n
  • Improve font accuracy for Windows 10 stealth browser personas.
    • \n
  • Fix email one-time codes being missed when they arrive before the code field appears.
    • \n
  • Improve detection of alphanumeric email one-time codes.
    • \n
  • Fix smart-scrape sessions being terminated when running behind a managed proxy.
    • \n
\n

v2.142.0

\n
    \n
  • Reconnect windows on hosted Cloud now match each plan's maximum session length.
    • \n
  • Reconnecting can no longer extend a session past its original time limit.
    • \n
\n

v2.141.0

\n
    \n
  • Improve automated screenshots and click accuracy, including clicking by screen position.
    • \n
  • Improve element targeting on pages with nested or embedded content.
    • \n
  • Add browser and device emulation options such as operating system, device, and screen size.
    • \n
  • Match language, timezone, and regional settings to the session's location.
    • \n
  • Free up leftover resources when sessions end, reducing memory growth over time.
    • \n
  • Fix live session viewers lingering after a session or connection closes.
    • \n
  • Restrict reconnecting to a browser session to the account that owns it.
    • \n
\n

v2.140.0

\n
    \n
  • Dependency updates.
    • \n
  • Detect an already-cleared captcha by default, removing an unnecessary wait on every check.
    • \n
  • Add support for storing session replays on your own storage service via SESSION_REPLAY_CLOUD_ENDPOINT.
    • \n
  • Stop rejecting session reattach and crawl status requests when the browser pool is busy.
    • \n
  • Prevent cloud-unit account balances from going below zero, and normalize existing negative balances.
    • \n
  • Fix session replays for persistent sessions not appearing in the dashboard.
    • \n
  • Preserve longer live-view timeouts on paid plans instead of rejecting the viewer link.
    • \n
  • Reduce delays when generating PDFs and screenshots.
    • \n
\n

v2.139.0

\n
    \n
  • Dependency updates.
    • \n
  • Improve usage reporting for browser profiles so activity is attributed to its originating source.
    • \n
  • Clear stealth sessions from Active Browsers as soon as the browser closes, instead of waiting for a timeout.
    • \n
\n

v2.138.0

\n
    \n
  • Add fleet-split labels to block metrics, enabling block-rate comparisons between worker groups.
    • \n
\n

v2.137.0

\n
    \n
  • Dependency updates.
    • \n
  • Make Live URLs available to authenticated users on every hosted Cloud plan, including Free.
    • \n
  • Increase the maximum Free browser-session duration from one minute to two minutes.
    • \n
  • Preserve legacy routing when BrowserQL migration settings are missing or lost.
    • \n
  • Cap captcha auto-solve retries and bill each challenge only once.
    • \n
\n

v2.136.0

\n
    \n
  • Dependency updates.
    • \n
  • Agent snapshots now include richer context about page elements and forms, improving automation accuracy.
    • \n
\n

v2.135.0

\n
    \n
  • Dependency updates.
    • \n
  • Allow screenshots and other captures after a credentialed login in the same session.
    • \n
  • Support one-time passcodes for logins that require multi-factor authentication.
    • \n
  • Report the original requester IP in request logs, configurable with TRUSTED_REQUESTER_IP_PROXIES.
    • \n
  • Support custom ad-blocking rule sets when ad blocking is enabled.
    • \n
\n

v2.134.0

\n
    \n
  • Updates to @browserless.io/browserless at v2.56.0.
    • \n
  • Update puppeteer-core to 25.7.0
    • \n
  • /agent/run now returns a standardized final result including the answer, success status, and reason.
    • \n
  • Improvements to /smart-scrape endpoint.
    • \n
\n

v2.133.0

\n
    \n
  • Dependency updates.
    • \n
  • Add optional reporting when a page load is blocked by anti-bot protection.
    • \n
  • Extract text from PDF pages during scraping.
    • \n
  • Fix intermittent captcha solve failures when using residential proxies.
    • \n
  • Fix screenshot and PDF capture failing on sites that redirect immediately after loading.
    • \n
  • Fix missing console output from iframes in stealth sessions.
    • \n
\n

v2.132.0

\n
    \n
  • Dependency updates.
    • \n
  • Proxy usage during autologin profile creation is now optional and chosen by the caller, avoiding unexpected metered usage.
    • \n
  • Invalid or plan-disallowed proxy settings are now rejected immediately with a clear error instead of a failed task.
    • \n
  • Solved captcha challenges are now properly applied to the page, so protected content loads instead of showing the challenge again.
    • \n
  • /smart-scrape now detects captcha walls and retries with a full browser instead of returning the challenge page as content.
    • \n
\n

v2.131.1

\n
    \n
  • Fix an explicit captcha solve being interrupted by automatic solving on the same page.
    • \n
  • Fix video playback failures in the chromium engine for commonly used media formats.
    • \n
  • Session URLs from /session now carry a per-session credential instead of your account token.
    • \n
  • Fix the reported GPU details in stealth sessions so they match the spoofed profile.
    • \n
\n

v2.131.0

\n
    \n
  • Skill capture results now report whether a skill was created or updated, with a clear rejection reason.
    • \n
  • Improve handling of malformed, unsafe, off-topic, or failed skill captures.
    • \n
  • Saved profiles now list only domains you actually logged into, with accurate login expiry dates.
    • \n
\n

v2.130.0

\n
    \n
  • Dependency updates.
    • \n
  • Saved authentication profiles now track when each site's sign-in expires, surfaced through the profile API.
    • \n
  • Profiles created before this release report no expiry details until their next save.
    • \n
  • Stealth sessions now emulate the platform Browserless runs on by default, with other options still selectable.
    • \n
\n

v2.129.0

\n
    \n
  • Dependency updates.
    • \n
  • Sessions blocked by an account's own spend limit now report a distinct error, separate from running out of credits.
    • \n
  • Live browsing keeps the viewer's cursor in sync with the page, including embedded content.
    • \n
  • Pressing Enter in a live session now activates links, buttons, and keyboard-driven widgets.
    • \n
  • Improve captcha solve reliability on protected sites, avoiding false failures and needless retries.
    • \n
  • Extend Windows browser emulation defaults to /unblock and /smart-scrape, with an option to override it.
    • \n
  • Allow individual accounts to keep the previous engine for /pdf, /screenshot, /content, and /export requests.
    • \n
\n

v2.128.0

\n
    \n
  • Stealth sessions now default to a Windows browser identity on cloud deployments, greatly improving solve rates.
    • \n
  • Self-hosted deployments keep their existing platform identity for consistent browser fingerprints.
    • \n
  • Improve captcha solver selection so the chosen solver matches the session's operating system.
    • \n
\n

v2.127.2

\n
    \n
  • Improve Akamai captcha success rates by preferring our own solver, with vendor fallback retained.
    • \n
\n

v2.127.1

\n
    \n
  • Improve captcha solve reliability on sites protected by advanced bot detection.
    • \n
\n

v2.127.0

\n
    \n
  • Add richer success and failure reporting for /agent/run, including run duration and outcome.
    • \n
  • Report completion for runs that end via cancellation, recovery, or queueing failure.
    • \n
  • Report rejected agent runs that previously went unrecorded.
    • \n
  • Track authenticated profile creation consistently, including profiles created by automatic login.
    • \n
  • Categorize automatic login failures so common causes are easier to identify.
    • \n
\n

v2.126.1

\n
    \n
  • Improve reliability of DataDome captcha solving with automatic retries.
    • \n
\n

v2.126.0

\n
    \n
  • Dependency updates.
    • \n
  • Improve request logs with clearer endpoint and source labels for agent and assistant traffic.
    • \n
  • Keep a stable exit IP for the whole session on stealth, BrowserQL, and /unblock requests.
    • \n
  • Fix pasted text being duplicated in live sessions.
    • \n
  • Fix pasted values not registering in some form fields during live sessions.
    • \n
\n

v2.124.0

\n
    \n
  • Dependency updates.
    • \n
  • Browser profiles created with the CLI now remember their capture settings, so a refresh replays them without extra options.
    • \n
  • Add support for solving Akamai security challenges, including interstitials that no longer fail the request.
    • \n
  • Add support for rotating-disc CAPTCHAs and improve slider CAPTCHA handling, retries, and outcome checks.
    • \n
  • Stealth sessions emulating an OS now report a consistent, realistic hardware profile, with optional pinning to a stable device.
    • \n
  • Stealth sessions report screen orientation more naturally, reducing detectable fingerprinting traces.
    • \n
  • Stop temporary files from accumulating and filling disk space on long-running workers.
    • \n
  • Fix live session clicks landing in the wrong place after the viewer is resized.
    • \n
  • Improve residential proxy routing so certain sites are reachable instead of failing to connect.
    • \n
\n

v2.123.1

\n
    \n
  • Updates to @browserless.io/browserless at v2.55.2.
    • \n
  • Fix session replays dropping page changes, so recordings now capture the full session.
    • \n
  • Keep recordings intact when an upload fails, so nothing is lost and can be retried.
    • \n
  • Improve anti-bot challenge detection and page classification, avoiding hangs on blocked pages.
    • \n
\n

v2.123.0

\n
    \n
  • Dependency updates.
    • \n
  • Show a clearer connection message when an account reaches its own spend limit, pointing to account settings.
    • \n
  • Add failure and timing telemetry for authenticated profiles to speed up support diagnosis.
    • \n
  • /unblock now returns a retryable error instead of a success when a page is still blocked.
    • \n
  • Fix /smart-scrape wrongly reporting a challenge on pages that were actually cleared.
    • \n
  • Improve internal captcha diagnostic tooling checks.
    • \n
\n

v2.122.0

\n
    \n
  • Dependency updates.
    • \n
  • Add request lifecycle markers to customer logs for clearer per-request visibility.
    • \n
  • Solve Amazon's account-verification image-grid captcha challenges.
    • \n
  • Improve browser identity consistency for stealth sessions.
    • \n
\n

v2.121.0

\n
    \n
  • Dependency updates.
    • \n
  • Automated sign-in now handles security checks, CAPTCHAs, and multi-factor prompts more reliably.
    • \n
  • Improve CAPTCHA and anti-bot handling on the /smart-scrape endpoint.
    • \n
  • Capture-only scrape requests now fail clearly when no requested output is produced.
    • \n
  • Improve accuracy of proxy bandwidth accounting for scrapes.
    • \n
  • Automatically turn successful browser automation runs into reusable skills, with quality checks.
    • \n
  • Browser sessions now start with a consistent desktop-sized window.
    • \n
  • Make switching to the newest window in BrowserQL deterministic and more resilient.
    • \n
\n

v2.120.0

\n
    \n
  • Improve log output.
    • \n
\n

v2.119.1

\n
    \n
  • Adjust exported metrics.
    • \n
\n

v2.119.0

\n
    \n
  • Dependency updates.
    • \n
  • Add a managed AI agent endpoint that runs a natural-language task in a real browser and returns structured results.
    • \n
  • Add an option to give Windows stealth sessions a coherent, consistent device fingerprint via STEALTH_WINDOWS_ARCHETYPES.
    • \n
  • Return a clear, actionable error from /pdf when generation fails, instead of a generic 500.
    • \n
\n

v2.118.0

\n
    \n
  • Update the default hosted-agent model for better intelligence, speed, and larger context; still overridable via OPENAI_MODEL and OPENAI_REASONING_EFFORT.
    • \n
  • Clarify the live session viewer's error when a requested timeout exceeds your plan's maximum, showing the limit and how to fix it.
    • \n
\n

v2.117.0

\n
    \n
  • Dependency updates.
    • \n
  • Add a /scrape endpoint to extract structured data from a page URL or raw HTML.
    • \n
  • Add a /skills endpoint for storing and reusing trusted automation skills.
    • \n
  • Add customer-visible structured request logs with a configurable log level.
    • \n
  • Keep stealth fingerprints consistent per session profile, including desktop screen size and scaling.
    • \n
  • Fix enterprise reCAPTCHA v3 being misclassified, improving solve reliability.
    • \n
  • Harden smart scraping against server-side request forgery.
    • \n
  • Fix popups and new tabs becoming invisible to clients during live sessions.
    • \n
  • Fix black cropping when capturing tall elements in screenshots.
    • \n
\n

v2.116.1

\n
    \n
  • Dependency updates.
    • \n
  • Bug fixes.
    • \n
  • Improve /crawl endpoint reliability.
    • \n
\n

v2.116.0

\n
    \n
  • Dependency updates.
    • \n
  • Updates to @browserless.io/browserless at v2.55.0.
    • \n
  • Fixes to browser profiles, crawls, and integrations.
    • \n
  • Improve error handling on the /unblock endpoint.
    • \n
  • Captcha auto-solve events reach client-created CDP sessions.
    • \n
  • Accept blockAdsInclude on connect and durable /session routes.
    • \n
\n

v2.115.0

\n
    \n
  • Add real-time BrowserQL subscriptions for console and network events.
    • \n
  • Accept live session requests with or without a JSON content type.
    • \n
  • Return from captcha solving faster when the page is already clear.
    • \n
  • Raise the default file-transfer size limit to 50 MB.
    • \n
\n

v2.114.0

\n
    \n
  • Dependency updates.
    • \n
  • Log the target URL for navigations that begin but never complete, making stuck sessions easier to debug.
    • \n
  • Add mobile Android device emulation for sessions.
    • \n
  • Fix live sessions freezing when a click opens a new browser tab.
    • \n
  • Revoked API keys now stop being accepted within seconds instead of minutes.
    • \n
  • Fix residential proxy errors when solving challenges after a redirect.
    • \n
  • Fix /unblock returning an unsolved challenge page as a successful response.
    • \n
\n

v2.113.0

\n
    \n
  • Fix sticky datacenter proxy sessions so they persist reliably instead of being recreated.
    • \n
  • Fix a crash on /smart-scrape and /search that returned a 500 and consumed credits.
    • \n
\n

v2.112.0

\n
    \n
  • Dependency updates.
    • \n
  • Upgrade the hosted agent to a stronger model with higher reasoning effort.
    • \n
  • Fix a black screen that could appear when starting a live session view.
    • \n
\n

v2.111.0

\n
    \n
  • Dependency updates.
    • \n
  • Update stealth session markers to reduce detection.
    • \n
\n

v2.110.0

\n
    \n
  • Dependency updates.
    • \n
  • Add per-session operating system emulation for stealth sessions via emulationOs.
    • \n
  • Improve stealth fingerprint consistency.
    • \n
  • Return the underlying error message from failed BQL mutations.
    • \n
  • Improve request logs, and include a request ID.
    • \n
  • Add an option to load only selected ad-blocking rulesets for faster session startup with blockAdsInclude.
    • \n
\n

v2.109.0

\n
    \n
  • Multiple API keys under the same account now share a single cloud-unit credit balance.
    • \n
  • Fix automated-login profiles not being saved after a successful login.
    • \n
\n

v2.108.2

\n
    \n
  • Dependency updates.
    • \n
  • Fix autologin agent failing to attach to its browser session in multi-worker deployments.
    • \n
\n

v2.108.1

\n
    \n
  • Dependency updates.
    • \n
  • Fix BQL script generation to produce consistent output.
    • \n
  • Improve crawl-delete response time for crawls with many URLs.
    • \n
  • Improve liveURL connection reliability through VPNs and corporate proxies.
    • \n
  • Fix BQL Windows desktop identity not applying on cloud deployments.
    • \n
  • Support multi-line statement bodies in BQL evaluate mutations.
    • \n
\n

v2.108.0

\n
    \n
  • Updates to @browserless.io/browserless at v2.54.2.
    • \n
  • Dependency updates.
    • \n
  • Add endpoint to list persistent sessions and their connection details.
    • \n
  • Add Script Generator endpoint with streaming output in multiple formats.
    • \n
  • Add opt-in Windows identity for stealth sessions to improve site compatibility.
    • \n
  • Add profile validation for agent connections.
    • \n
  • Fix credential autologin in certain session flows.
    • \n
  • Fix Turnstile solving on some sites.
    • \n
\n

v2.107.0

\n
    \n
  • Dependency updates.
    • \n
  • Updates to @browserless.io/browserless at v2.54.1.
    • \n
  • Agent endpoint (/chromium/agent) gains uploadFile and getDownloads methods for file transfers.
    • \n
  • Add autologin profiles powered by 1Password.
    • \n
  • Improve stealth mode.
    • \n
\n

v2.106.0

\n
    \n
  • Dependency updates.
    • \n
  • Updates to @browserless.io/browserless at v2.54.0.
    • \n
  • Additional per-route metric.
    • \n
  • Disable Chrome optimization-guide model downloads.
    • \n
  • Return 403 when a navigation is blocked.
    • \n
  • Drop Playwright 1.42 support and add Playwright 1.61.
    • \n
\n

v2.105.0

\n
    \n
  • Dependency updates.
    • \n
  • Add BQL mutations: emulateMediaType, addScriptTag, addStyleTag, fulfill, and markdown.
    • \n
  • Extend BQL mutations: goto accepts referer, waitForSelector supports hidden, viewport supports hasTouch/landscape, and pdf supports fullPage.
    • \n
  • Fix acceptInsecureCerts not taking effect in stealth mode.
    • \n
  • Fix proxied requests.
    • \n
\n

v2.104.0

\n
    \n
  • Add CDP proxy commands Browserless.uploadFile and Browserless.fileDownloaded.
    • \n
  • Fix BQL stealth reconnect().
    • \n
\n

v2.103.0

\n
    \n
  • Dependency updates.
    • \n
  • Add 1Password credential support.
    • \n
  • Unblock API reconnection fix.
    • \n
  • Fix navigation guards.
    • \n
  • /export with includeResources: true now bundles cross-origin assets.
    • \n
  • Improve reCAPTCHA detection accuracy.
    • \n
\n

v2.102.0

\n
    \n
  • Dependency updates.
    • \n
  • Updates to @browserless.io/browserless at v2.52.2.
    • \n
  • Add session-replay support to the /unblock endpoint.
    • \n
  • Fix extension loading failures.
    • \n
\n

v2.101.0

\n
    \n
  • Dependency updates.
    • \n
  • Updates to @browserless.io/browserless at v2.52.1.
    • \n
  • Allow MCP agents to create, save, and reuse browser profiles across sessions.
    • \n
  • Log output re-leveled to surface warnings while reducing routine noise.
    • \n
  • Isolate WebSocket errors in live URL, VHS recording, and CDP proxy sessions.
    • \n
  • Add WS_MAX_PAYLOAD env var to raise the WebSocket payload limit for large CDP responses.
    • \n
  • Additional metrics for per-route latency, queue wait, browser acquire time, and capacity gauges.
    • \n
\n

v2.100.0

\n
    \n
  • Dependency updates.
    • \n
  • Updates to @browserless.io/browserless at v2.52.0.
    • \n
  • Add solve(type: audio) BQL mutation for solving reCAPTCHA v2 audio challenges.
    • \n
  • Add datacenter proxy network alongside residential proxies for sessions, REST APIs, scraping, and BQL. Datacenter traffic is billed at a lower unit rate.
    • \n
  • Fix if/ifnot BQL blocks running mutations in parallel instead of sequentially.
    • \n
  • Fix stealth browser launch hanging when the blockAds or record is specified.
    • \n
\n

v2.99.1

\n
    \n
  • Bug fixes.
    • \n
  • Dependency updates.
    • \n
\n

v2.99.0

\n
    \n
  • Dependency updates.
    • \n
  • Add a hosted agent endpoint (/chromium/cli) where Browserless runs the LLM and drives the browser to complete a task, streaming progress to the CLI; LLM usage is billed as separate agent units.
    • \n
  • Move the /unblock endpoint onto the BrowserQL stack, adding configurable waits, an optional WebSocket endpoint, and screenshots that honor the requested image format.
    • \n
  • Add an Arkoselabs/FunCaptcha solver, detect captchas inside same-origin iframes, and improve rotate-captcha accuracy with honest solve reporting.
    • \n
  • Make screenshots and PDFs best-effort after captcha solving, so a post-solve page navigation no longer fails the whole request.
    • \n
  • Improve stealth realism so sessions more closely resemble a real-world browser (on by default).
    • \n
  • Honor the operator argument in the waitForResponse, waitForRequest, if, and ifnot BQL mutations.
    • \n
  • Return partial results from the BQL response() mutation when an individual response body is unavailable.
    • \n
  • Bypass the limiter for BQL reconnect requests so in-progress sessions aren't dropped when a worker is under load.
    • \n
  • Adjust consumption for requests that fail validation (for example a missing url).
    • \n
  • Add OpenTelemetry session metrics (completed/rejected/active) and per-endpoint http.route span labels.
    • \n
\n

v2.98.1

\n
    \n
  • Updates to @browserless.io/browserless at v2.51.1 — Node.js 24.16.0, NPM 11.16.0, and puppeteer-core 25.1.0.
    • \n
  • New authenticate mutation.
    • \n
  • Bug fixes
    • \n
\n

v2.98.0

\n
    \n
  • Dependency updates.
    • \n
  • Add a new authenticate BQL mutation for HTTP authentication.
    • \n
  • Improve press and hold captcha solving.
    • \n
  • Fix snapshot accessibility attribute type handling.
    • \n
  • Improve secret redaction in OpenTelemetry observability data.
    • \n
\n

v2.97.1

\n
    \n
  • Dependency updates.
    • \n
\n

v2.96.3

\n
    \n
  • Improve Cloudflare and Turnstile captcha solving.
    • \n
  • Improve stealth reliability against Cloudflare for Puppeteer and Playwright.
    • \n
  • Return 429 for new sessions when the worker is at capacity.
    • \n
  • Improve 429 observability in OpenTelemetry traces.
    • \n
  • Add rotate captcha solving.
    • \n
\n

v2.96.2

\n
    \n
  • Improve scrape, map, and search reliability on slow sites.
    • \n
\n

v2.96.1

\n
    \n
  • Improve /smart-scrape reliability against protected sites with target-aware proxy selection and improved captcha detection and solving.
    • \n
  • Improve /unblock reliability with a request-wide timeout deadline, more robust browser startup, and waitUntil support for finer navigation control.
    • \n
  • Fix copy-paste in LiveURL when the viewer is embedded in a cross-origin iframe (such as the Browserless account app).
    • \n
\n

v2.96.0

\n
    \n
  • Improve adblock list build resilience by falling back to a bundled snapshot when the upstream source is unreachable.
    • \n
\n

v2.95.2

\n
    \n
  • Fix in-page WebSocket connections for /function and /download endpoints being blocked on HTTPS deployments due to mixed-content restrictions.
    • \n
\n

v2.95.1

\n
    \n
  • Dependency updates.
    • \n
  • Add Browserless.refreshProfile CDP method to update an existing profile's auth state in place without creating a duplicate.
    • \n
  • Updates to @browserless.io/browserless at v2.49.0.
    • \n
  • Reduce production Docker image size by removing development tooling from the final image.
    • \n
\n

v2.95.0

\n
    \n
  • Dependency updates.
    • \n
  • Fix billing and Browser Session Ended tracking for persistent session and reconnect WebSocket connections (/session/connect/:id and /reconnect/:id); each WebSocket connection is now billed independently, restoring usage accounting for persistent-session traffic.
    • \n
  • Add POST /profile/upload and POST /profile/refresh endpoints to create a profile from a pre-captured auth state or replace an existing profile's state in place, with server-side sanitization of cookies, origins, and IndexedDB plus a diagnostics field describing what was filtered or truncated.
    • \n
  • Fix LiveURL OAuth login for authenticated profiles, and default the browser type to stealth when creating a profile without specifying one.
    • \n
\n

v2.94.1

\n
    \n
  • Dependency updates.
    • \n
  • Cap live viewers at 5 per session ID on /live/<id> and return 429 Too Many Requests once exceeded, freeing slots automatically when viewers disconnect.
    • \n
  • Include captcha detection and classification in snapshot captures, giving agents better visibility into security challenges encountered during automation.
    • \n
  • Add an optional profile parameter to crawl requests for authenticated scraping; crawls now end early on critical errors, truncate oversized error messages, and return 503 if the profile service is unavailable.
    • \n
\n

v2.94.0

\n
    \n
  • Updates to @browserless.io/browserless at v2.48.3.
    • \n
  • Dependency updates.
    • \n
  • Fix agent snapshot generation when pages contain malformed or empty HTML attributes, so snapshots no longer fail on attribute encoding edge cases.
    • \n
  • Add an optional profile parameter to /scrape requests for server-side hydration of authenticated browser profiles; requests that use a profile now require an API token and return clearer validation errors.
    • \n
  • LiveURL sessions now show distinct end-of-session messages for timeouts versus manual closures, and the message is delivered before the socket disconnects so users actually see it.
    • \n
  • Credit limit error messages now link to https://browserless.io/account/upgrade instead of the generic account page, and have minor grammar fixes.
    • \n
\n

v2.93.0

\n
    \n
  • Update @browserless.io/browserless to v2.48.2
    • \n
  • Improve proxy city targeting
    • \n
  • Add tab management methods for agents
    • \n
\n

v2.92.3

\n
    \n
  • Add Akamai captcha solving support.
    • \n
\n

v2.92.2

\n
    \n
  • Improve browser fingerprint consistency for CPU architecture and font rendering in Docker images.
    • \n
  • Dependency updates
    • \n
\n

v2.92.1

\n
    \n
  • Enable agentic browsing for all accounts
    • \n
  • Dependency updates
    • \n
\n

v2.92.0

\n
    \n
  • Add authenticated profiles: capture a logged-in browser's cookies, localStorage, and IndexedDB once via Browserless.saveProfile, then reuse on any session with ?profile=<name>.
    • \n
  • Add HTTP API for profile lifecycle: POST /profile, GET /profiles, GET|PUT|DELETE /profile/:name.
    • \n
\n

v2.91.0

\n
    \n
  • Add route for agentic browsing
    • \n
\n

v2.90.6

\n
    \n
  • Set default /crawl scrape timeout to 150s.
    • \n
  • Add customer.id to OpenTelemetry resource attributes.
    • \n
  • Add Content-Disposition header for PDF API responses.
    • \n
  • Improve captcha handling by hiding the auto-challenge.
    • \n
  • Cache uBOL-home release metadata in the adblock build.
    • \n
\n

v2.90.5

\n
    \n
  • Update search limits: Free 1→3, Prototyping 3→5, Starter 5→10, Scale 10→20.
    • \n
  • Dependency updates.
    • \n
\n

v2.90.4

\n
    \n
  • Improve DataDome captcha solving reliability.
    • \n
\n

v2.90.3

\n
    \n
  • Add captcha solving support for browser-use sessions.
    • \n
\n

v2.90.2

\n
    \n
  • Add DataDome captcha solving support.
    • \n
  • Improve smart-scrape captcha detection and post-challenge navigation.
    • \n
  • Add captcha solving support for browser-use sessions.
    • \n
  • Improve /crawl API with enhanced orchestration and documentation.
    • \n
  • Fix timeout override for applicable routes.
    • \n
  • Fix session TTL display for browser sessions.
    • \n
  • Bug fixes and improvements.
    • \n
\n

v2.90.1

\n
    \n
  • Bug fixes and improvements.
    • \n
\n

v2.90.0

\n
    \n
  • New crawl API for scalable web crawling.
    • \n
  • Fix BQL close() overwriting reconnect keepUntil with zero TTL.
    • \n
\n

v2.89.2

\n
    \n
  • Updates to @browserless.io/browserless at v2.46.0.
    • \n
  • Fix 400 errors caused by strict Record<string,string> types in API schemas.
    • \n
  • Fix Docker multi-heavy base image tagging.
    • \n
  • Dependency updates.
    • \n
\n

v2.89.1

\n
    \n
  • Updates to @browserless.io/browserless at v2.45.0.
    • \n
  • Fix proxy SSL certificate errors (ERR_CERT_AUTHORITY_INVALID).
    • \n
  • Improve proxy vendor health checks and failover reliability.
    • \n
  • Harden URL validation against SSRF and DNS rebinding.
    • \n
  • Fix session TTL management.
    • \n
  • Fix stopRecording hanging in certain error conditions.
    • \n
  • Fix recording quality for VHS sessions.
    • \n
  • Unify scrape format types across REST API schemas.
    • \n
\n

v2.89.0

\n
    \n
  • Add metadata enrichment for /map endpoint.
    • \n
  • Add option to transfer base64 instead of binary for recordings.
    • \n
  • Fix liveURL blank screen.
    • \n
  • Fix bypass CSP for virtual keyboard and emulated <select>s.
    • \n
  • Fix high CPU consumption for /map.
    • \n
  • Add --disable-component-extensions-with-background-pages to stealth args.
    • \n
\n

v2.88.2

\n
    \n
  • Updates to browserless.io/browserless at v2.43.0.
    • \n
\n

v2.88.1

\n
    \n
  • New /map API.
    • \n
  • Add emulateComponents option for liveURL.
    • \n
  • Dependency updates.
    • \n
\n

v2.87.0

\n
    \n
  • Deprecate codes in waitForResponse mutation, favoring statuses instead.
    • \n
  • Fix <select /> elements in liveURL view.
    • \n
  • Enable uploaded extensions cache.
    • \n
  • New /search API.
    • \n
\n

v2.86.1

\n
    \n
  • Power-scrape endpoint is now smart-scrape.
    • \n
  • Improve Turnstile captcha detection and solving.
    • \n
  • Improve session replay in reconnect sessions.
    • \n
  • Improve stealth chromium for persistent sessions.
    • \n
\n

v2.86.0

\n
    \n
  • Updates to browserless.io/browserless at v2.42.0.
    • \n
  • Updates NodeJS to 24.14.0.
    • \n
  • Supports puppeteer-core version 24.37.5.
    • \n
  • Dependency updates.
    • \n
  • Added support for loading extensions from session metadata.
    • \n
\n

v2.85.1

\n
    \n
  • Supports HTTPs third party proxies in BQL
    • \n
  • Fixes mobile typing bug in liveURL
    • \n
\n

v2.85.0

\n
    \n
  • Updates to browserless.io/browserless at v2.41.0.
    • \n
  • Supports puppeteer-core version 24.37.4.
    • \n
  • OTEL support.
    • \n
\n

v2.84.2

\n
    \n
  • Fix power scraper initialization bug
    • \n
\n

v2.84.1

\n
    \n
  • Fix query param validation bug
    • \n
\n

v2.84.0

\n
    \n
  • New power scrape endpoint for intelligent content extraction.
    • \n
  • Fix external proxies in BQL incorrectly charging proxy units.
    • \n
\n

v2.83.0

\n
    \n
  • Fix proxy consumption bug
    • \n
  • Fix screencasting video dimensions
    • \n
  • Improve docker image size
    • \n
\n

v2.82.1

\n
    \n
  • Bug fixes.
    • \n
\n

v2.82.0

\n
    \n
  • Added new proxy vendor.
    • \n
  • New processKeepAlive flag.
    • \n
  • Fix screencasting video dimensions.
    • \n
  • liveURL connection issues.
    • \n
\n

v2.81.0

\n
    \n
  • Updates to browserless.io/browserless at v2.39.0.
    • \n
  • Session replay improvements.
    • \n
  • Improve proxy mutations in BQL.
    • \n
  • Additional captchas support.
    • \n
  • Supports playwright-core versions 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0, 1.53.2, 1.54.2, 1.55.1, 1.56.1, 1.57.0 and 1.58.1.
    • \n
  • Supports puppeteer-core version 24.36.1.
    • \n
\n

v2.80.1

\n
    \n
  • Improve CAPTCHA detection and solving.
    • \n
  • Support for external proxy server parameter.
    • \n
\n

v2.80.0

\n
    \n
  • Updates to browserless.io/browserless at v2.38.4.
    • \n
  • Updates NodeJS to 24.13.0.
    • \n
  • Improve captcha solving performance.
    • \n
  • Additional captchas support.
    • \n
  • Supports playwright-core versions 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0, 1.53.2, 1.54.2, 1.55.1, 1.56.1 and 1.57.0.
    • \n
  • Supports puppeteer-core version 24.36.0.
    • \n
\n

v2.79.2

\n
    \n
  • Improve CAPTCHA detection and solving.
    • \n
\n

v2.79.1

\n
    \n
  • Improve liveURL rendering in high DPI displays.
    • \n
  • Bug fixes.
    • \n
\n

v2.79.0

\n
    \n
  • Improve CAPTCHA detection mechanism.
    • \n
  • Fix bug where deeply nested elements weren't found in nested shadow DOMs
    • \n
\n

v2.78.3

\n
    \n
  • Improved BQL proxy URL regeneration on reconnects
    • \n
  • Streamlined event logging
    • \n
\n

v2.78.2

\n
    \n
  • Improved proxy connection reliability
    • \n
\n

v2.78.1

\n
    \n
  • Upgraded browser tracking TTL
    • \n
\n

v2.78.0

\n
    \n
  • Improved stealth and bot detection evasion capabilities
    • \n
\n

v2.77.1

\n
    \n
  • Fix black screen issue with live urls
    • \n
\n

v2.77.0

\n
    \n
  • New MAX_RECONNECT_TIME launch flag
    • \n
  • Ensure the WS connection is always closed when using the /kill endpoint
    • \n
  • Improve captcha detection
    • \n
  • Fix bug in live URL that added an offset to mouse events
    • \n
\n

v2.76.0

\n
    \n
  • Improve proxy reliability and performance
    • \n
  • Fix third party proxies for BQL
    • \n
  • Improve captcha solving performance
    • \n
\n

v2.75.0

\n
    \n
  • Improved proxy reliability and performance
    • \n
  • Enhanced captcha detection
    • \n
  • Better stealth mode compatibility
    • \n
  • Session replay improvements
    • \n
\n

v2.74.4

\n
    \n
  • Stealth route enhancements
    • \n
  • Connection stability improvements
    • \n
\n

v2.74.3

\n
    \n
  • Enhanced captcha handling
    • \n
\n

v2.74.2

\n
    \n
  • Bug fixes and improvements
    • \n
\n

v2.74.1

\n
    \n
  • Added proxy provider configuration options
    • \n
\n

v2.74.0

\n
    \n
  • Dependency updates
    • \n
  • Improved captcha support for BQL
    • \n
  • Performance optimizations
    • \n
\n

v2.73.2

\n
    \n
  • Improve Resdential Proxy Quaility
    • \n
\n

v2.73.1

\n
    \n
  • Minor improvements in liveURL client
    • \n
\n

v2.73.0

\n
    \n
  • Add proxyLocaleMatch parameter to set browser language based on proxy country
    • \n
  • Fix BQL session replay
    • \n
\n

v2.72.1

\n
    \n
  • Deprecate verify mutation
    • \n
  • Improve captcha callback function caller
    • \n
  • Improve internal logs
    • \n
\n

v2.72.0

\n
    \n
  • Added new proxy vendor
    • \n
  • New solveImageCaptcha mutation
    • \n
  • Better handle proxy requests that contains cities
    • \n
\n

v2.71.1

\n
    \n
  • Fix bug in /unblock API where it errored if the screenshot parameter was not set
    • \n
  • Allow all paid accounts to use the screencasting API
    • \n
\n

v2.71.0

\n
    \n
  • Implemented new proxy provider
    • \n
  • Improved Cloudflare CAPTCHA solver
    • \n
\n

v2.70.2

\n
    \n
  • Updated proxy provider priority
    • \n
\n

v2.70.1

\n
    \n
  • Improved recaptcha-v3 solver for speed and reliability improvements
    • \n
  • Added /proxy/cities API endpoint for getting a list of supported proxy cities
    • \n
  • Improved selectors for normal captcha, and Cloudflare captcha
    • \n
\n

v2.70.0

\n
    \n
  • Improved recaptcha v3 support
    • \n
  • Add fallback between captcha solvers
    • \n
  • Improve event logging
    • \n
\n

v2.69.1

\n
    \n
  • Dependency updates.
    • \n
  • Improved recaptcha v2 support in stealth routes
    • \n
\n

v2.69.0

\n
    \n
  • Match the browsers to the stealth endpoints.
    • \n
  • Cloudflare captcha tracking improvements
    • \n
\n

v2.68.5

\n
    \n
  • Added support for Turnstile Cloudflare captcha
    • \n
  • Fixed amplitude attempt events to track Cloudflare captchas correctly
    • \n
  • Added captcha subtype to amplitude events
    • \n
\n

v2.68.4

\n
    \n
  • clean disk space before building docker images
    • \n
\n

v2.68.3

\n
    \n
  • Restore automation of timezone and add proxy city validation changes
    • \n
\n

v2.68.1

\n
    \n
  • Dependency updates.
    • \n
  • Bug fixes and improvements
    • \n
\n

v2.68.0

\n
    \n
  • Dependency updates.
    • \n
  • Allow --disable-bundled-ppapi-flash, --disable-dev-shm-usage, --disable-domain-reliability, --disable-gpu, --disable-speech-api, --disable-webgl, and --wm-window-animations-disabled flags to be used.
    • \n
  • Improve CAPTCHA solvers.
    • \n
\n

v2.67.1

\n
    \n
  • Bug fixes and improvements
    • \n
\n

v2.67.0

\n
    \n
  • Updates to browserless.io/browserless at v2.38.2.
    • \n
  • Supports playwright-core versions 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0, 1.53.2, 1.54.2, and 1.55.1.
    • \n
  • Supports puppeteer-core version 24.26.1.
    • \n
  • Allow using Brave on BQL
    • \n
  • Captcha selector fixes
    • \n
\n

v2.66.2

\n
    \n
  • Critical security bug fix
    • \n
\n

v2.66.1

\n
    \n
  • Critical security bug fix
    • \n
\n

v2.66.0

\n
    \n
  • Revert proxy city and timezone changes
    • \n
  • Upgrade Playwright, Puppeteer and Browserless
    • \n
  • Upgrade Chrome to 141.0
    • \n
  • Support for Capy challenges
    • \n
\n

v2.65.2

\n
    \n
  • Improve CAPTCHA detection and solving.
    • \n
\n

v2.65.1

\n
    \n
  • Add city database for proxy validation
    • \n
  • Validate cities against supported proxy providers
    • \n
  • Automate timezone based on proxy location
    • \n
\n

v2.65.0

\n
    \n
  • Dependency updates
    • \n
  • New @export directive
    • \n
  • Fix timeout in solve captcha mutations
    • \n
  • Normalize allowed cities for proxies
    • \n
  • Fix Amplitude IDs for sessions
    • \n
\n

v2.64.3

\n
    \n
  • Fix Amplitude logging error
    • \n
\n

v2.64.1

\n
    \n
  • Allow using solveCaptchas on stealth routes.
    • \n
\n

v2.64.0

\n
    \n
  • Dependency updates.
    • \n
  • New feature: auto solve captcha.
    • \n
  • Improve captcha resolution state polling.
    • \n
  • Fix captcha solving edge cases.
    • \n
\n

v2.63.3

\n
    \n
  • Dependency updates.
    • \n
  • Log more event properties on Captcha Solve Error events.
    • \n
  • Allow sending acceptInsecureCerts as query param.
    • \n
  • Improve captcha-solving parameter sanitation.
    • \n
\n

v2.63.2

\n
    \n
  • Dependency updates.
    • \n
  • Updates to @browserless.io/browserless 2.37.1.
    • \n
\n

v2.63.1

\n
    \n
  • Dependency updates.
    • \n
  • Switches to ioredis for cloud-unit platform.
    • \n
\n

v2.63.0

\n
    \n
  • Dependency updates.
    • \n
  • Major /stealth route enhancements.
    • \n
  • Many testing updates for internal stability.
    • \n
  • Fixes BrowserQL goto calls that return a chrome-related error.
    • \n
  • Other fixes and updates for stealth and captcha solving.
    • \n
\n

v2.62.1

\n
    \n
  • Dependency updates.
    • \n
  • Better timeout messages on cloud platform.
    • \n
  • Other testing fixes.
    • \n
\n

v2.62.0

\n
    \n
  • Dependency updates.
    • \n
  • Update to @browserless.io/browserless 2.37.0.
    • \n
  • Minor build updates and unit-test enhancements.
    • \n
  • BrowserQL click mutation fixes and reliability improvements.
    • \n
  • Fix /pdf, /screenshot and other REST APIs with requestInterceptors that contain base64 responses.
    • \n
  • Other minor fixes and improvements.
    • \n
\n

v2.61.2

\n
    \n
  • Dependency updates.
    • \n
  • Cleanup of internal docs.
    • \n
  • Fixes and issue with /unblock API's waitForFn properties.
    • \n
\n

v2.61.1

\n
    \n
  • Dependency updates.
    • \n
  • Fixes an issue where /unblock might orphan the browser process.
    • \n
  • Logging and analytics improvements in cloud.
    • \n
\n

v2.61.0

\n
    \n
  • Dependency updates.
    • \n
  • Update to Ubuntu 24.04.
    • \n
  • Update @browserless.io/browserless to 2.36.0.
    • \n
  • New switchToWindow BrowserQL API.
    • \n
  • Stealth enhancements and updates.
    • \n
  • Prettier changes on source, logging cleanup.
    • \n
\n

v2.60.1

\n
    \n
  • Dependency updates.
    • \n
  • BrowserQL documentation updates and enhancements.
    • \n
  • Analytical improvements on the cloud-unit platform.
    • \n
\n

v2.60.0

\n
    \n
  • Dependency updates.
    • \n
  • Replay feature is now shipped for cloud-unit.
    • \n
  • Documentation cleanup and updates.
    • \n
  • Updated request parsing and parameter handling.
    • \n
  • Hybrid URL logging clean up.
    • \n
  • Stealth enhancements and improvements.
    • \n
\n

v2.59.0

\n
    \n
  • Dependency updates.
    • \n
  • Stealth updates to all stealth enabled routes.
    • \n
  • Fixes and updates to our captcha-solving capabilities.
    • \n
  • Use npm ci for production builds (prevents unintentional package updates).
    • \n
  • Other fixes and updates.
    • \n
\n

v2.57.0

\n
    \n
  • New fingerprint management and rotation for browserless' /stealth CDP routes!
    • \n
  • Updates to browserless.io/browserless@2.34.1
    • \n
  • Supports playwright-core versions 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0, 1.53.1, and 1.54.2.
    • \n
  • Supports puppeteer-core version 24.16.2.
    • \n
  • Captcha solving updates and improvements.
    • \n
\n

v2.56.0

\n
    \n
  • Updates to browserless.io/browserless at v2.34.0.
    • \n
  • Supports playwright-core versions 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0, 1.53.1, and 1.54.2.
    • \n
  • Supports puppeteer-core version 24.16.1.
    • \n
  • Supports using of Chrome Extensions in cloud-unit products. Please refer to documentation on how to use this new feature.
    • \n
  • Sessions API now support interoperability with BrowserQL.
    • \n
  • Introduces a new vendor for Captcha Solving.
    • \n
  • New environment variables:
      \n
    • EXTENSIONS_DIR The directory to store extensions onto.
      • \n
    • LOAD_EXTENSIONS_FROM_CLOUD Whether or not to load extensions from a S3 compatible URL.
      • \n
    • EXTENSIONS_CLOUD_BUCKET The bucket for extensions to be loaded from.
      • \n
    • EXTENSIONS_CLOUD_REGION The region to load extensions from.
      • \n
    • CAPSOLVER_API_KEY An API key to use for when Capsolver is used for captcha solving.
      • \n
    \n
    • \n
\n

v2.55.0

\n
    \n
  • Dependency updates.
    • \n
  • Reverts some breaking stealth changes in favor of stability.
    • \n
  • Adds a "mode" option in BQL's removeAttributes parameter for better HTML parsing.
    • \n
\n

v2.54.0

\n
    \n
  • Dependency updates.
    • \n
  • New LiveURL updates that include an optional showBrowserInterface for rendering all the tabs.
    • \n
  • Fixes some issues with stealth and headers that Chrome generates.
    • \n
\n

v2.53.1

\n
    \n
  • Revert live-URL updates until they're backwards compatible.
    • \n
\n

v2.53.0

\n
    \n
  • Dependency updates.g
    • \n
  • New viewport API for BQL.
    • \n
  • Consolidation of some internal utilities for consistency sake.
    • \n
  • Big improvements to the /stealth routes for CDP libraries.
    • \n
  • You can solveCaptcha without specifying the vendor in BQL.
    • \n
  • Support for proxying through residential proxy providers.
    • \n
  • Fixes an issue in BQL that can cause a browser to stay open when navigating.
    • \n
  • LiveURL can now support multi-tabs workflows.
    • \n
  • Testing fixes.
    • \n
\n

v2.52.4

\n
    \n
  • Fixes an issue when deleting sessions
    • \n
\n

v2.52.3

\n
    \n
  • Updates to proxying for future compatibility
    • \n
\n

v2.52.2

\n
    \n
  • Fixes an issue where proxying can cause un-necessary latency
    • \n
\n

v2.52.1

\n
    \n
  • Fix BQL navigation not filtering out iframe page events.
    • \n
\n

v2.52.0

\n
    \n
  • Dependency updates.
    • \n
  • Fixes navigation (goto, back, forward) issues in BQL for goto, forward and backward actions.
    • \n
  • blockConsentModal is now default to false in BQL as it sometimes causes sites to hang indefinitely when loading.
    • \n
  • New amazonWaf for BQL captcha solving.
    • \n
  • New downloading handling forcing all downloads to be in a configurable path by setting a DOWNLOAD_DIR.
    • \n
  • Fix page's created by playwright's context object hanging.
    • \n
  • Fix issues with CDP-based screen-recording.
    • \n
  • Other fixes, improvements, and reliability enhancements.
    • \n
  • Bumps puppeteer-core to 24.12.1.
    • \n
  • Bumps playwright-core to 1.54.1.
    • \n
  • Drops support for playwright-core at 1.49.
    • \n
  • Supports:
      \n
    • puppeteer-core: 24.12.1
      • \n
    • playwright-core: 1.41.2, 1.42.1, 1.43.1, 1.44.1, 1.45.3, 1.46.1, 1.47.2, 1.48.2, 1.49.1, 1.50.1, 1.51.1, 1.52.0,
      • \n
    • Chromium: 139.0.7258.5
      • \n
    • Firefox: 140.0.2
      • \n
    • Webkit: 26.0
      • \n
    • Chrome: 138.0.7204.101 (amd64 only)
      • \n
    • Edge: 138.0.3351.83 (amd64 only)
      • \n
    \n
    • \n
\n" }, "openapi": "3.0.0", "paths": { "/chrome/content": { "post": { "definitions": {}, "description": "A JSON-based API. Given a \"url\" or \"html\" field, runs and returns HTML content after the page has loaded and JavaScript has parsed.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/definitions/Credentials" }, { "type": "null" } ] }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/definitions/GoToOptions" }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/definitions/Viewport" }, { "type": "null" } ] }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" } } } }, "responses": { "200": { "content": { "text/html": { "schema": { "description": "An HTML payload of the website or HTML after JavaScript\nparsing and execution.", "type": "string", "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "An HTML payload of the website or HTML after JavaScript\nparsing 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": [ "Browser REST APIs" ] } }, "/chrome/download": { "post": { "definitions": {}, "description": "A JSON or JavaScript content-type API for returning files Chrome has downloaded during\nthe execution of puppeteer code, which is ran inside context of the browser.\nBrowserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it.\nYou can load external libraries via the \"import\" syntax, and import ESM-style modules\nthat are written for execution inside of the browser. Once your script is finished, any\ndownloaded files from Chromium are returned back with the appropriate content-type header.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "$ref": "#/definitions/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the downloads\nthemselves, 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\nthemselves, 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": [ "Browser REST APIs" ] } }, "/chrome/function": { "post": { "definitions": {}, "description": "A JSON or JavaScript content-type API for running puppeteer code in the browser's context.\nBrowserless sets up a blank page, injects your puppeteer code, and runs it.\nYou can optionally load external libraries via the \"import\" module that are meant for browser usage.\nValues returned from the function are checked and an appropriate content-type and response is sent back\nto your HTTP call.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "$ref": "#/definitions/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the function\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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": [ "Browser REST APIs" ] } }, "/json/new": { "put": { "definitions": {}, "description": "Returns a JSON payload that acts as a pass-through to the DevTools /json/new HTTP API in Chromium.\nBrowserless mocks this payload so that remote clients can connect to the underlying \"webSocketDebuggerUrl\"\nwhich 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\nlibraries 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": [ "Browser REST APIs" ] } }, "/json/protocol": { "get": { "definitions": {}, "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": [ "Browser REST APIs" ] } }, "/json/version": { "get": { "definitions": {}, "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\nlibraries 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": [ "Browser REST APIs" ] } }, "/chrome/pdf": { "post": { "definitions": {}, "description": "A JSON-based API for getting a PDF binary from either a supplied\n\"url\" or \"html\" payload in your request. Many options exist for\ninjecting cookies, request interceptors, user-agents and waiting for\nselectors, timers and more.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/definitions/Credentials" }, { "type": "null" } ] }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/definitions/GoToOptions" }, "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\nclasses used to inject values into them:\n\n- `date` formatted print date\n\n- `title` document title\n\n- `url` document location\n\n- `pageNumber` current page number\n\n- `totalPages` total pages in the document", "type": "string" }, "footerTemplate": { "description": "HTML template for the print footer. Has the same constraints and support\nfor 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\ndeclared in the `width` or `height` or `format` option.", "type": "boolean" }, "margin": { "description": "Set the PDF margins.", "$ref": "#/definitions/PDFMargin" }, "path": { "description": "The path to save the file to.", "type": "string" }, "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.\n\nThe 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\nactivating the page using {@link Page.bringToFront} if the page is in the\nbackground.", "type": "boolean" }, "fullPage": { "type": "boolean" } } }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/definitions/Viewport" }, { "type": "null" } ] }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" } } } }, "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": [ "Browser REST APIs" ] } }, "/chrome/performance": { "post": { "definitions": {}, "description": "Run lighthouse performance audits with a supplied \"url\" in your JSON payload.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "budgets": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "config": { "type": "object", "properties": {}, "additionalProperties": true }, "url": { "type": "string" } }, "type": "object", "required": [ "url" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON body", "type": "object", "properties": {}, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON 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": [ "Browser REST APIs" ] } }, "/chrome/scrape": { "post": { "definitions": {}, "description": "A JSON-based API that returns text, html, and meta-data from a given list of\nselectors. Debugging information is available by sending in the appropriate\nflags in the \"debugOpts\" property. Responds with an array of JSON objects.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "$ref": "#/definitions/Credentials" }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "debugOpts": { "type": "object", "properties": { "console": { "type": "boolean" }, "cookies": { "type": "boolean" }, "html": { "type": "boolean" }, "network": { "type": "boolean" }, "screenshot": { "type": "boolean" } }, "additionalProperties": false }, "elements": { "type": "array", "items": { "$ref": "#/definitions/ScrapeElementSelector" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "description": "The supported subset of puppeteer's goto options: `waitUntil` (mapped onto\nbap-ts's set — an array reduces to its first entry), `timeout` (clamped to\nthe route ceiling), and `referer`. Other puppeteer goto fields are not\nforwarded.", "type": "object", "properties": { "timeout": { "type": "number" }, "waitUntil": { "anyOf": [ { "type": "array", "items": { "$ref": "#/definitions/PuppeteerLifeCycleEvent" } }, { "enum": [ "domcontentloaded", "load", "networkidle0", "networkidle2" ], "type": "string" } ] }, "referer": { "type": "string" } }, "additionalProperties": false }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "status": { "type": "number" }, "headers": { "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E", "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String." }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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": { "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "$ref": "#/definitions/Viewport" }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/ScrapeGroupResult" } }, "debug": { "type": "object", "properties": { "console": { "type": "array", "items": { "type": "string" } }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/Cookie" } }, "html": { "type": "string" }, "network": { "type": "object", "properties": { "inbound": { "type": "array", "items": { "$ref": "#/definitions/InboundResponse" } }, "outbound": { "type": "array", "items": { "$ref": "#/definitions/OutboundRequest" } } }, "additionalProperties": false, "required": [ "inbound", "outbound" ] }, "screenshot": { "type": "string" } }, "additionalProperties": false, "required": [ "console", "cookies", "html", "network", "screenshot" ] } }, "additionalProperties": false, "required": [ "data", "debug" ], "definitions": { "ScrapeGroupResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/ScrapeElementResult" } }, "selector": { "type": "string" } }, "additionalProperties": false, "required": [ "results", "selector" ] }, "ScrapeElementResult": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false, "required": [ "name", "value" ] } }, "height": { "type": "number" }, "html": { "type": "string" }, "left": { "type": "number" }, "text": { "type": "string" }, "top": { "type": "number" }, "width": { "type": "number" } }, "additionalProperties": false, "required": [ "attributes", "height", "html", "left", "text", "top", "width" ] }, "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\nsession 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": { "$ref": "#/definitions/CookieSameSite_2", "description": "Cookie SameSite type." }, "priority": { "$ref": "#/definitions/CookiePriority", "description": "Cookie Priority. Supported only in Chrome." }, "sourceScheme": { "$ref": "#/definitions/CookieSourceScheme", "description": "Cookie source scheme type. Supported only in Chrome." }, "partitionKey": { "description": "Cookie partition key. In Chrome, it matches the top-level site the\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/definitions/CookiePartitionKey" }, { "type": "string" } ] } }, "additionalProperties": false, "required": [ "domain", "expires", "name", "path", "secure", "session", "size", "value" ] }, "CookieSameSite_2": { "description": "Represents the cookie's 'SameSite' status:\nhttps://tools.ietf.org/html/draft-west-first-party-cookies", "enum": [ "Default", "Lax", "None", "Strict" ], "type": "string" }, "CookiePriority": { "description": "Represents the cookie's 'Priority' status:\nhttps://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\n\"Unset\" allows protocol clients to emulate legacy cookie scope for the scheme.\nThis is a temporary ability and it will be removed in the future.", "enum": [ "NonSecure", "Secure", "Unset" ], "type": "string" }, "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\nto the endpoint that set the cookie.\n\nIn 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\nthe topLevelSite.\n\nSupported only in Chrome.", "type": "boolean" } }, "additionalProperties": false, "required": [ "sourceOrigin" ] }, "InboundResponse": { "type": "object", "properties": { "headers": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E" }, "status": { "type": "number" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "status", "url" ] }, "Record": { "type": "object", "additionalProperties": false }, "OutboundRequest": { "type": "object", "properties": { "headers": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E" }, "method": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "method", "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": "/chrome/scrape", "tags": [ "Browser REST APIs" ] } }, "/chrome/screenshot": { "post": { "definitions": {}, "description": "A JSON-based API for getting a screenshot binary from either a supplied\n\"url\" or \"html\" payload in your request. Many options exist including\ncookies, user-agents, setting timers and network mocks.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/definitions/Credentials" }, { "type": "null" } ] }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/definitions/GoToOptions" }, "html": { "type": "string" }, "options": { "$ref": "#/definitions/ScreenshotOptions" }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/definitions/Viewport" }, { "type": "null" } ] }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" } } } }, "responses": { "200": { "content": { "image/png": { "schema": { "type": "text" } }, "image/jpeg": { "schema": { "type": "text" } }, "text/plain": { "schema": { "type": "text" } } }, "description": "Response can either be a text/plain base64 encoded body\nor 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": [ "Browser REST APIs" ] } }, "/chromium/content": { "post": { "definitions": {}, "description": "A JSON-based API. Given a \"url\" or \"html\" field, runs and returns HTML content after the page has loaded and JavaScript has parsed.\n\n**Note:** This endpoint is also available at: `/content` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/definitions/Credentials" }, { "type": "null" } ] }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/definitions/GoToOptions" }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/definitions/Viewport" }, { "type": "null" } ] }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" } } } }, "responses": { "200": { "content": { "text/html": { "schema": { "description": "An HTML payload of the website or HTML after JavaScript\nparsing and execution.", "type": "string", "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "An HTML payload of the website or HTML after JavaScript\nparsing 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": [ "Browser REST APIs" ] } }, "/chromium/download": { "post": { "definitions": {}, "description": "A JSON or JavaScript content-type API for returning files Chrome has downloaded during\nthe execution of puppeteer code, which is ran inside context of the browser.\nBrowserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it.\nYou can load external libraries via the \"import\" syntax, and import ESM-style modules\nthat are written for execution inside of the browser. Once your script is finished, any\ndownloaded files from Chromium are returned back with the appropriate content-type header.\n\n**Note:** This endpoint is also available at: `/download` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "$ref": "#/definitions/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the downloads\nthemselves, 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\nthemselves, 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": [ "Browser REST APIs" ] } }, "/chromium/function": { "post": { "definitions": {}, "description": "A JSON or JavaScript content-type API for running puppeteer code in the browser's context.\nBrowserless sets up a blank page, injects your puppeteer code, and runs it.\nYou can optionally load external libraries via the \"import\" module that are meant for browser usage.\nValues returned from the function are checked and an appropriate content-type and response is sent back\nto your HTTP call.\n\n**Note:** This endpoint is also available at: `/function` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "$ref": "#/definitions/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the function\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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": [ "Browser REST APIs" ] } }, "/chromium/performance": { "post": { "definitions": {}, "description": "Run lighthouse performance audits with a supplied \"url\" in your JSON payload.\n\n**Note:** This endpoint is also available at: `/performance` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "budgets": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "config": { "type": "object", "properties": {}, "additionalProperties": true }, "url": { "type": "string" } }, "type": "object", "required": [ "url" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON body", "type": "object", "properties": {}, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON 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": [ "Browser REST APIs" ] } }, "/chromium/scrape": { "post": { "definitions": {}, "description": "A JSON-based API that returns text, html, and meta-data from a given list of selectors.\nDebugging information is available by sending in the appropriate flags in the \"debugOpts\"\nproperty. Responds with an array of JSON objects.\n\n**Note:** This endpoint is also available at: `/scrape` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/definitions/Credentials" }, { "type": "null" } ] }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "debugOpts": { "$ref": "#/definitions/ScrapeDebugOptions" }, "elements": { "type": "array", "items": { "$ref": "#/definitions/ScrapeElementSelector" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/definitions/GoToOptions" }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/definitions/Viewport" }, { "type": "null" } ] }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ] } } } }, "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": "#/definitions/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": "#/definitions/InBoundRequest" } }, "outbound": { "type": "array", "items": { "$ref": "#/definitions/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\nsession 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\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/definitions/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\nto the endpoint that set the cookie.\n\nIn 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\nthe topLevelSite.\n\nSupported 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": [ "Browser REST APIs" ] } }, "/edge/content": { "post": { "definitions": {}, "description": "A JSON-based API. Given a \"url\" or \"html\" field, runs and returns HTML content after the page has loaded and JavaScript has parsed.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/definitions/Credentials" }, { "type": "null" } ] }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/definitions/GoToOptions" }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/definitions/Viewport" }, { "type": "null" } ] }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" } } } }, "responses": { "200": { "content": { "text/html": { "schema": { "description": "An HTML payload of the website or HTML after JavaScript\nparsing and execution.", "type": "string", "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "An HTML payload of the website or HTML after JavaScript\nparsing 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": [ "Browser REST APIs" ] } }, "/edge/download": { "post": { "definitions": {}, "description": "A JSON or JavaScript content-type API for returning files Chrome has downloaded during\nthe execution of puppeteer code, which is ran inside context of the browser.\nBrowserless sets up a blank page, a fresh download directory, injects your puppeteer code, and then executes it.\nYou can load external libraries via the \"import\" syntax, and import ESM-style modules\nthat are written for execution inside of the browser. Once your script is finished, any\ndownloaded files from Chromium are returned back with the appropriate content-type header.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "$ref": "#/definitions/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the downloads\nthemselves, 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\nthemselves, 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": [ "Browser REST APIs" ] } }, "/edge/function": { "post": { "definitions": {}, "description": "A JSON or JavaScript content-type API for running puppeteer code in the browser's context.\nBrowserless sets up a blank page, injects your puppeteer code, and runs it.\nYou can optionally load external libraries via the \"import\" module that are meant for browser usage.\nValues returned from the function are checked and an appropriate content-type and response is sent back\nto your HTTP call.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "$ref": "#/definitions/JSONSchema" } }, "application/javascript": { "schema": { "type": "string" } } } }, "responses": { "200": { "content": { "*/*": { "schema": { "description": "Responses are determined by the returned value of the function\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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\nitself. Binary responses (PDF's, screenshots) are returned back\nas binary data, and primitive JavaScript values are returned back\nby 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": [ "Browser REST APIs" ] } }, "/edge/pdf": { "post": { "definitions": {}, "description": "A JSON-based API for getting a PDF binary from either a supplied\n\"url\" or \"html\" payload in your request. Many options exist for\ninjecting cookies, request interceptors, user-agents and waiting for\nselectors, timers and more.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/definitions/Credentials" }, { "type": "null" } ] }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/definitions/GoToOptions" }, "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\nclasses used to inject values into them:\n\n- `date` formatted print date\n\n- `title` document title\n\n- `url` document location\n\n- `pageNumber` current page number\n\n- `totalPages` total pages in the document", "type": "string" }, "footerTemplate": { "description": "HTML template for the print footer. Has the same constraints and support\nfor 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\ndeclared in the `width` or `height` or `format` option.", "type": "boolean" }, "margin": { "description": "Set the PDF margins.", "$ref": "#/definitions/PDFMargin" }, "path": { "description": "The path to save the file to.", "type": "string" }, "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.\n\nThe 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\nactivating the page using {@link Page.bringToFront} if the page is in the\nbackground.", "type": "boolean" }, "fullPage": { "type": "boolean" } } }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/definitions/Viewport" }, { "type": "null" } ] }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" } } } }, "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": [ "Browser REST APIs" ] } }, "/edge/performance": { "post": { "definitions": {}, "description": "Run lighthouse performance audits with a supplied \"url\" in your JSON payload.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "budgets": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "config": { "type": "object", "properties": {}, "additionalProperties": true }, "url": { "type": "string" } }, "type": "object", "required": [ "url" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON body", "type": "object", "properties": {}, "additionalProperties": true, "$schema": "http://json-schema.org/draft-07/schema#" } } }, "description": "The response of the lighthouse stats. Response objects are\ndetermined by the type of budgets and config in the POST\nJSON 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": [ "Browser REST APIs" ] } }, "/edge/scrape": { "post": { "definitions": {}, "description": "A JSON-based API that returns text, html, and meta-data from a given list of selectors.\nDebugging information is available by sending in the appropriate flags in the \"debugOpts\"\nproperty. Responds with an array of JSON objects.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/definitions/Credentials" }, { "type": "null" } ] }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "debugOpts": { "$ref": "#/definitions/ScrapeDebugOptions" }, "elements": { "type": "array", "items": { "$ref": "#/definitions/ScrapeElementSelector" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/definitions/GoToOptions" }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/definitions/Viewport" }, { "type": "null" } ] }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ] } } } }, "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": "#/definitions/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": "#/definitions/InBoundRequest" } }, "outbound": { "type": "array", "items": { "$ref": "#/definitions/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\nsession 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\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/definitions/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\nto the endpoint that set the cookie.\n\nIn 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\nthe topLevelSite.\n\nSupported 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": [ "Browser REST APIs" ] } }, "/edge/screenshot": { "post": { "definitions": {}, "description": "A JSON-based API for getting a screenshot binary from either a supplied\n\"url\" or \"html\" payload in your request. Many options exist including\ncookies, user-agents, setting timers and network mocks.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "anyOf": [ { "$ref": "#/definitions/Credentials" }, { "type": "null" } ] }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "$ref": "#/definitions/GoToOptions" }, "html": { "type": "string" }, "options": { "$ref": "#/definitions/ScreenshotOptions" }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "headers": { "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String.", "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E" }, "status": { "type": "number" }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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\nMissing optional values will be filled in by the target with what it would normally use.", "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "anyOf": [ { "$ref": "#/definitions/Viewport" }, { "type": "null" } ] }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" } } } }, "responses": { "200": { "content": { "image/png": { "schema": { "type": "text" } }, "image/jpeg": { "schema": { "type": "text" } }, "text/plain": { "schema": { "type": "text" } } }, "description": "Response can either be a text/plain base64 encoded body\nor 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": [ "Browser REST APIs" ] } }, "/active": { "get": { "definitions": {}, "description": "Returns a simple \"204\" HTTP code, with no response, indicating that the service itself is up and running.\nUseful 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": [ "Management REST APIs" ] } }, "/kill/+([0-9a-zA-Z-_])": { "get": { "definitions": {}, "description": "Kill running sessions based on BrowserId or TrackingId.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "browserId", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": [ "Management REST APIs" ] } }, "/meta": { "get": { "definitions": {}, "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": [ "Management REST APIs" ] } }, "/": { "get": { "definitions": {}, "description": "Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol.\n\n**Note:** This endpoint is also available at: `/chromium` for backwards compatibility.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "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.\nAccepts 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": [ "Browser WebSocket APIs" ] } }, "/devtools/browser/*": { "get": { "definitions": {}, "description": "Connect to an already-running Chromium process with a library like\npuppeteer, or others, that work over chrome-devtools-protocol. Chromium\nmust already be launched in order to not return a 404.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "/devtools/browser/*", "tags": [ "Browser WebSocket APIs" ] } }, "/chrome": { "get": { "definitions": {}, "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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "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.\nAccepts 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": [ "Browser WebSocket APIs" ] } }, "/function/connect/*": { "get": { "definitions": {}, "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 nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "/function/connect/*", "tags": [ "Browser WebSocket APIs" ] } }, "/devtools/page/*": { "get": { "definitions": {}, "description": "Connect to an existing page in Chromium with a library like\nchrome-remote-interface or others that work the page websocketDebugger\nURL. You can get this unique URL by calling the /json/list API\nor by finding the page's unique ID from your library of choice.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "/devtools/page/*", "tags": [ "Browser WebSocket APIs" ] } }, "/chrome/playwright": { "get": { "definitions": {}, "description": "Connect to Chromium with any playwright style library.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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/playwright", "tags": [ "Browser WebSocket APIs" ] } }, "/chromium": { "get": { "definitions": {}, "description": "Launch and connect to Chromium with a library like puppeteer or others that work over chrome-devtools-protocol.\n\n**Note:** This endpoint is also available at: `/` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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", "tags": [ "Browser WebSocket APIs" ] } }, "/chromium/playwright": { "get": { "definitions": {}, "description": "Connect to Chromium with any playwright style library.\n\n**Note:** This endpoint is also available at: `/playwright/chromium` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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/playwright", "tags": [ "Browser WebSocket APIs" ] } }, "/edge": { "get": { "definitions": {}, "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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "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.\nAccepts 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": [ "Browser WebSocket APIs" ] } }, "/edge/playwright": { "get": { "definitions": {}, "description": "Connect to Chromium with any playwright style library.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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/playwright", "tags": [ "Browser WebSocket APIs" ] } }, "/firefox/playwright": { "get": { "definitions": {}, "description": "Connect to Firefox with any playwright-compliant library.\n\n**Note:** This endpoint is also available at: `/playwright/firefox` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, 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" }, "env": { "description": "Environment for the browser process. Honored by both puppeteer.launch and\nplaywright.launchServer. Set server-side to give the session its own TMPDIR\n(see generateScratchDir); a caller-supplied value is merged under it, since\na session must not be able to point its scratch back at the shared temp dir.\n\nThat merge happens on the object handed to `launch` only. It is kept off\nthe session's stored `launchOptions`, which /sessions serves verbatim.", "$ref": "#/definitions/Record%3Cstring%2Cstring%7Cundefined%3E" }, "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.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "/firefox/playwright", "tags": [ "Browser WebSocket APIs" ] } }, "/webkit/playwright": { "get": { "definitions": {}, "description": "Connect to Webkit with any playwright-compliant library.\n\n**Note:** This endpoint is also available at: `/playwright/webkit` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "/webkit/playwright", "tags": [ "Browser WebSocket APIs" ] } }, "/browser/*/live/*": { "delete": { "definitions": {}, "description": "Closes an active live URL owned by the specified browser. Returns 204 with no body.", "parameters": [], "requestBody": { "content": {} }, "responses": { "204": { "code": 204, "description": "Live URL closed; no response body.", "message": "HTTP/1.1 204 No 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": "/browser/*/live/*", "tags": [ "Management REST APIs", "Browser REST APIs" ] }, "get": { "definitions": {}, "description": "Reports live URL status and completion reason until its browser closes.", "parameters": [], "requestBody": { "content": {} }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Whether the link is open, expired, or closed.", "enum": [ "closed", "expired", "open" ], "type": "string" }, "reason": { "anyOf": [ { "$ref": "#/definitions/LiveURLCompleteReason", "description": "How the link ended, or null while open." }, { "type": "null" } ] }, "interactable": { "description": "Whether the viewer can click and type.", "type": "boolean" }, "viewerCount": { "description": "Number of currently connected viewers; zero for ended links.", "type": "number" }, "expiresAt": { "description": "Scheduled expiration time in epoch milliseconds.", "type": "number" } }, "additionalProperties": false, "required": [ "expiresAt", "interactable", "reason", "status", "viewerCount" ], "definitions": { "LiveURLCompleteReason": { "enum": [ "closed", "timeout", "userDone", "userFailed", "viewerDisconnected" ], "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": "/browser/*/live/*", "tags": [ "Management REST APIs", "Browser REST APIs" ] } }, "/browser/*/live": { "post": { "definitions": {}, "description": "Creates a live URL (view-only by default; pass interactable: true for a link\na person can act through) for a currently-running browser, identified by\nbrowserId. Hosted authenticated Cloud plans, including Free, can use this\nroute. Explicitly disabled and unlicensed deployments remain ineligible.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "interactable": { "description": "Allow the viewer to click and type. Defaults to false.", "type": "boolean" }, "timeout": { "description": "Link lifetime in milliseconds, capped at 15 minutes and remaining session time.", "type": "number" }, "quality": { "description": "Integer image quality from 1 to 100. Defaults to 70.", "type": "number" }, "type": { "description": "Image format. Defaults to jpeg; png only accepts explicit quality 100.", "enum": [ "jpeg", "png" ], "type": "string" }, "resizable": { "description": "Allow the viewer to resize the browser. Defaults to false.", "type": "boolean" }, "showBrowserInterface": { "description": "Show the browser interface. Defaults to true.", "type": "boolean" }, "instructions": { "description": "Instructions shown to the human viewer.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "liveURL": { "description": "URL the viewer opens to watch or interact with the browser.", "type": "string" }, "liveURLId": { "description": "Identifier used to check or close this live URL.", "type": "string" } }, "additionalProperties": false, "required": [ "liveURL", "liveURLId" ], "$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": "/browser/*/live", "tags": [ "Management REST APIs", "Browser REST APIs" ] } }, "/browser/*": { "delete": { "definitions": {}, "description": "Terminates a browser instance by browserId. When browser ownership enforcement\nis enabled, 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": [ "Management REST APIs", "Browser REST APIs" ] } }, "/chrome/export": { "post": { "definitions": {}, "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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "url": { "description": "The URL of the site you want to archive.", "type": "string" }, "gotoOptions": { "$ref": "#/definitions/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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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.\nWhen true, the response will be a zip file containing the HTML and all resources.\nWhen false or not provided, the response will be the raw content (default behavior).", "type": "boolean" } }, "type": "object", "required": [ "url" ] } } } }, "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": [ "Browser REST APIs" ] } }, "/chrome/unblock": { "post": { "definitions": {}, "description": "Unblocks the provided URL from being blocked due to bot detection.\nReturns a payload of Cookies, HTML, a base64 encoded screenshot,\nand a \"browserWSEndpoint\" to allow connecting to the browser when\nspecified in the JSON Payload. Only supports CDP or Puppeteer\nlike libraries when connecting to the \"browserWSEndpoint\".", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "OS to emulate: `windows`/`macos`/`linux`/`android`. Omitted → native Linux\nwith no device profile; an explicit `linux` still gets one." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "description": "Records the unblock session for replay (rrweb) and uploads on cleanup, reusing the\nBQL pipeline. Connection-level flag via `?replay=true`. Defaults to false.", "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "description": "With `browserWSEndpoint`, persists captcha-solving on the kept-alive session so\nreconnects auto-solve. Connection-level flag via `?solveCaptchas=true`. Defaults false.", "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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 true, browserless proceeds when \"awaited\" events fail or timeout\n(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\nfuture 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": "How long to keep the browser alive for re-connection when browserWSEndpoint\nis requested. Maximum of 30000 (30 seconds).", "type": "number" }, "gotoOptions": { "$ref": "#/definitions/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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ] } } } }, "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.\nValue is \"null\" when the request body specifies cookies: false.", "type": "array", "items": { "$ref": "#/definitions/UnblockCookie" } }, "content": { "description": "The HTML content of the page once it is passed bot detection.\nValue is \"null\" when the request body specifies content: false.", "type": "string" }, "browserWSEndpoint": { "description": "The browserWSEndpoint of the response when the POST body contains a\nbrowserWSEndpoint: true property", "type": "string" }, "ttl": { "description": "Time the browser stays alive until shutdown; zero when browserWSEndpoint: false.\nLimit is 60000 (60 seconds).", "type": "number" }, "screenshot": { "description": "A base64 encoded JPEG of the of the final site page.", "type": "string" }, "solved": { "description": "Whether a detected anti-bot challenge was successfully solved during the unblock.\nFalse when none was present or a present one could not be solved.", "type": "boolean" } }, "additionalProperties": false, "required": [ "browserWSEndpoint", "content", "cookies", "screenshot", "solved", "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": [ "Browser REST APIs" ] } }, "/chromium/export": { "post": { "definitions": {}, "description": "Exports a webpage to a PDF or image format. This API is useful for generating reports, screenshots, or PDFs of web pages.\n\n**Note:** This endpoint is also available at: `/export` for backwards compatibility.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "url": { "description": "The URL of the site you want to archive.", "type": "string" }, "gotoOptions": { "$ref": "#/definitions/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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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.\nWhen true, the response will be a zip file containing the HTML and all resources.\nWhen false or not provided, the response will be the raw content (default behavior).", "type": "boolean" } }, "type": "object", "required": [ "url" ] } } } }, "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": [ "Browser REST APIs" ] } }, "/scrape": { "post": { "definitions": {}, "description": "A JSON-based API that returns text, html, and meta-data from a given list of\nselectors. Debugging information is available by sending in the appropriate\nflags in the \"debugOpts\" property. Responds with an array of JSON objects.\n\n**Note:** This endpoint is also available at: `/chromium/scrape` for backwards compatibility.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": { "addScriptTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "$ref": "#/definitions/Credentials" }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "debugOpts": { "type": "object", "properties": { "console": { "type": "boolean" }, "cookies": { "type": "boolean" }, "html": { "type": "boolean" }, "network": { "type": "boolean" }, "screenshot": { "type": "boolean" } }, "additionalProperties": false }, "elements": { "type": "array", "items": { "$ref": "#/definitions/ScrapeElementSelector" } }, "emulateMediaType": { "type": "string" }, "gotoOptions": { "description": "The supported subset of puppeteer's goto options: `waitUntil` (mapped onto\nbap-ts's set — an array reduces to its first entry), `timeout` (clamped to\nthe route ceiling), and `referer`. Other puppeteer goto fields are not\nforwarded.", "type": "object", "properties": { "timeout": { "type": "number" }, "waitUntil": { "anyOf": [ { "type": "array", "items": { "$ref": "#/definitions/PuppeteerLifeCycleEvent" } }, { "enum": [ "domcontentloaded", "load", "networkidle0", "networkidle2" ], "type": "string" } ] }, "referer": { "type": "string" } }, "additionalProperties": false }, "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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "status": { "type": "number" }, "headers": { "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E", "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String." }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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": { "$ref": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "$ref": "#/definitions/Viewport" }, "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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/ScrapeGroupResult" } }, "debug": { "type": "object", "properties": { "console": { "type": "array", "items": { "type": "string" } }, "cookies": { "type": "array", "items": { "$ref": "#/definitions/Cookie" } }, "html": { "type": "string" }, "network": { "type": "object", "properties": { "inbound": { "type": "array", "items": { "$ref": "#/definitions/InboundResponse" } }, "outbound": { "type": "array", "items": { "$ref": "#/definitions/OutboundRequest" } } }, "additionalProperties": false, "required": [ "inbound", "outbound" ] }, "screenshot": { "type": "string" } }, "additionalProperties": false, "required": [ "console", "cookies", "html", "network", "screenshot" ] } }, "additionalProperties": false, "required": [ "data", "debug" ], "definitions": { "ScrapeGroupResult": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/ScrapeElementResult" } }, "selector": { "type": "string" } }, "additionalProperties": false, "required": [ "results", "selector" ] }, "ScrapeElementResult": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "additionalProperties": false, "required": [ "name", "value" ] } }, "height": { "type": "number" }, "html": { "type": "string" }, "left": { "type": "number" }, "text": { "type": "string" }, "top": { "type": "number" }, "width": { "type": "number" } }, "additionalProperties": false, "required": [ "attributes", "height", "html", "left", "text", "top", "width" ] }, "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\nsession 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": { "$ref": "#/definitions/CookieSameSite_2", "description": "Cookie SameSite type." }, "priority": { "$ref": "#/definitions/CookiePriority", "description": "Cookie Priority. Supported only in Chrome." }, "sourceScheme": { "$ref": "#/definitions/CookieSourceScheme", "description": "Cookie source scheme type. Supported only in Chrome." }, "partitionKey": { "description": "Cookie partition key. In Chrome, it matches the top-level site the\npartitioned cookie is available in. In Firefox, it matches the\nsource origin in the\n{@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.", "anyOf": [ { "$ref": "#/definitions/CookiePartitionKey" }, { "type": "string" } ] } }, "additionalProperties": false, "required": [ "domain", "expires", "name", "path", "secure", "session", "size", "value" ] }, "CookieSameSite_2": { "description": "Represents the cookie's 'SameSite' status:\nhttps://tools.ietf.org/html/draft-west-first-party-cookies", "enum": [ "Default", "Lax", "None", "Strict" ], "type": "string" }, "CookiePriority": { "description": "Represents the cookie's 'Priority' status:\nhttps://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\n\"Unset\" allows protocol clients to emulate legacy cookie scope for the scheme.\nThis is a temporary ability and it will be removed in the future.", "enum": [ "NonSecure", "Secure", "Unset" ], "type": "string" }, "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\nto the endpoint that set the cookie.\n\nIn 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\nthe topLevelSite.\n\nSupported only in Chrome.", "type": "boolean" } }, "additionalProperties": false, "required": [ "sourceOrigin" ] }, "InboundResponse": { "type": "object", "properties": { "headers": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E" }, "status": { "type": "number" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "status", "url" ] }, "Record": { "type": "object", "additionalProperties": false }, "OutboundRequest": { "type": "object", "properties": { "headers": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E" }, "method": { "type": "string" }, "url": { "type": "string" } }, "additionalProperties": false, "required": [ "headers", "method", "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": "/scrape", "tags": [ "Browser REST APIs" ] } }, "/unblock": { "post": { "definitions": {}, "description": "Unblocks the provided URL from being blocked due to bot detection.\nReturns a payload of Cookies, HTML, a base64 encoded screenshot,\nand a \"browserWSEndpoint\" to allow connecting to the browser when\nspecified in the JSON Payload. Only supports CDP or Puppeteer\nlike libraries when connecting to the \"browserWSEndpoint\".\n\n**Note:** This endpoint is also available at: `/chromium/unblock` for backwards compatibility.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "OS to emulate: `windows`/`macos`/`linux`/`android`. Omitted → native Linux\nwith no device profile; an explicit `linux` still gets one." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "description": "Records the unblock session for replay (rrweb) and uploads on cleanup, reusing the\nBQL pipeline. Connection-level flag via `?replay=true`. Defaults to false.", "type": "boolean" } }, { "in": "query", "name": "solveCaptchas", "schema": { "description": "With `browserWSEndpoint`, persists captcha-solving on the kept-alive session so\nreconnects auto-solve. Connection-level flag via `?solveCaptchas=true`. Defaults false.", "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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 true, browserless proceeds when \"awaited\" events fail or timeout\n(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\nfuture 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": "How long to keep the browser alive for re-connection when browserWSEndpoint\nis requested. Maximum of 30000 (30 seconds).", "type": "number" }, "gotoOptions": { "$ref": "#/definitions/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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" ] } } } }, "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.\nValue is \"null\" when the request body specifies cookies: false.", "type": "array", "items": { "$ref": "#/definitions/UnblockCookie" } }, "content": { "description": "The HTML content of the page once it is passed bot detection.\nValue is \"null\" when the request body specifies content: false.", "type": "string" }, "browserWSEndpoint": { "description": "The browserWSEndpoint of the response when the POST body contains a\nbrowserWSEndpoint: true property", "type": "string" }, "ttl": { "description": "Time the browser stays alive until shutdown; zero when browserWSEndpoint: false.\nLimit is 60000 (60 seconds).", "type": "number" }, "screenshot": { "description": "A base64 encoded JPEG of the of the final site page.", "type": "string" }, "solved": { "description": "Whether a detected anti-bot challenge was successfully solved during the unblock.\nFalse when none was present or a present one could not be solved.", "type": "boolean" } }, "additionalProperties": false, "required": [ "browserWSEndpoint", "content", "cookies", "screenshot", "solved", "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": [ "Browser REST APIs" ] } }, "/proxy/cities": { "get": { "definitions": {}, "description": "Returns a list of available cities for proxy connections.\n\nThis endpoint requires city proxying to be enabled on your plan.\n\nQuery Parameters:\n- country (optional): Filter cities by two-letter country code (e.g., 'US', 'GB', 'DE')\n\nThe response includes a list of available cities grouped by country code.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "country", "schema": { "description": "Optional two-letter country code to filter cities by country (e.g., 'US', 'GB', 'DE').", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": [ "Management REST APIs", "Browser REST APIs" ] } }, "/map": { "post": { "definitions": {}, "description": "Primarily discovers URLs from the site's sitemap, supplemented\nwith link extraction from the page via the smart-scrape strategy\npipeline (HTTP-first, browser fallback for JS-rendered pages).\nUse 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" } } ], "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" ] } } } }, "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": "/map", "tags": [ "Browser REST APIs" ] } }, "/pdf": { "post": { "definitions": {}, "description": "A JSON-based API for getting a PDF binary from either a supplied\n\"url\" or \"html\" payload in your request. Many options exist for\ninjecting cookies, request interceptors, user-agents and waiting for\nselectors, timers and more.\n\n**Note:** This endpoint is also available at: `/chromium/pdf` for backwards compatibility.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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.\nIncludes 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\nclasses used to inject values into them:\n\n- `date` formatted print date\n\n- `title` document title\n\n- `url` document location\n\n- `pageNumber` current page number\n\n- `totalPages` total pages in the document", "type": "string" }, "footerTemplate": { "description": "HTML template for the print footer. Has the same constraints and support\nfor 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": "#/definitions/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\ndeclared in the `width` or `height` or `format` option.", "type": "boolean" }, "margin": { "$ref": "#/definitions/PDFMargin", "description": "Set the PDF margins." }, "path": { "description": "The path to save the file to.", "type": "string" }, "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.\n\nThe 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\nactivating the page using {@link Page.bringToFront} if the page is in the\nbackground.", "type": "boolean" }, "fullPage": { "type": "boolean" } } }, "addScriptTag": { "description": "An array of script tags to add to the page before performing actions.\nEach object can contain either a `url`, or a `content` property.", "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "description": "An array of style tags to add to the page before performing actions.\nEach object can contain either a `url`, or a `content` property.", "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "$ref": "#/definitions/Credentials", "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless will attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "description": "An array of cookies to set on the page before navigation.\nEach cookie object should contain at least `name` and `value` properties.", "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "emulateMediaType": { "description": "Changes the CSS media type of the page. Accepts values like \"screen\" or \"print\".", "type": "string" }, "gotoOptions": { "$ref": "#/definitions/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.\nRequests matching these patterns will be aborted.", "type": "array", "items": { "type": "string" } }, "rejectResourceTypes": { "description": "An array of resource types to reject during page load.\nCommon 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.\nEach 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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "status": { "type": "number" }, "headers": { "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E", "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String." }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "$ref": "#/definitions/Viewport", "description": "The viewport dimensions and settings for the page.\nIncludes 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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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" } } } }, "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": [ "Browser REST APIs" ] } }, "/screenshot": { "post": { "definitions": {}, "description": "A JSON-based API for getting a screenshot binary from either a supplied\n\"url\" or \"html\" payload in your request. Many options exist including\ncookies, user-agents, setting timers and network mocks.\n\n**Note:** This endpoint is also available at: `/chromium/screenshot` for backwards compatibility.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": "#/definitions/ScreenshotOptions", "description": "Screenshot options based on Puppeteer's ScreenshotOptions interface.\nIncludes properties like `type`, `quality`, `fullPage`, `clip`, etc." }, "addScriptTag": { "description": "An array of script tags to add to the page before performing actions.\nEach object can contain either a `url`, or a `content` property.", "type": "array", "items": { "$ref": "#/definitions/FrameAddScriptTagOptions" } }, "addStyleTag": { "description": "An array of style tags to add to the page before performing actions.\nEach object can contain either a `url`, or a `content` property.", "type": "array", "items": { "$ref": "#/definitions/FrameAddStyleTagOptions" } }, "authenticate": { "$ref": "#/definitions/Credentials", "description": "Credentials for HTTP authentication. Contains `username` and `password` properties." }, "bestAttempt": { "description": "When bestAttempt is set to true, browserless will attempt to proceed\nwhen \"awaited\" events fail or timeout. This includes things like\ngoto, waitForSelector, and more.", "type": "boolean" }, "cookies": { "description": "An array of cookies to set on the page before navigation.\nEach cookie object should contain at least `name` and `value` properties.", "type": "array", "items": { "$ref": "#/definitions/CookieParam" } }, "emulateMediaType": { "description": "Changes the CSS media type of the page. Accepts values like \"screen\" or \"print\".", "type": "string" }, "gotoOptions": { "$ref": "#/definitions/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.\nRequests matching these patterns will be aborted.", "type": "array", "items": { "type": "string" } }, "rejectResourceTypes": { "description": "An array of resource types to reject during page load.\nCommon 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.\nEach 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\ncorresponding 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\ncorresponding responses to use in order to fulfill those requests.", "type": "string" }, "response": { "additionalProperties": false, "type": "object", "properties": { "status": { "type": "number" }, "headers": { "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E", "description": "Optional response headers.\n\nThe record values will be converted to string following:\nArrays' values will be mapped to String\n(Used when you need multiple headers with the same name).\nNon-arrays will be converted to String." }, "contentType": { "type": "string" }, "body": { "description": "A string representation of the body to return. Can be a base64-encoded\nstring 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": "#/definitions/Protocol.Emulation.UserAgentMetadata" }, "platform": { "type": "string" } }, "additionalProperties": false }, "viewport": { "$ref": "#/definitions/Viewport", "description": "The viewport dimensions and settings for the page.\nIncludes 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.\nIf polling is a number, then it is treated as an interval in milliseconds\nat which the function would be executed. If polling is a string,\nthen 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).\nPass 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.\nUseful 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" } } } }, "responses": { "200": { "content": { "image/png": { "schema": { "type": "text" } }, "image/jpeg": { "schema": { "type": "text" } }, "text/plain": { "schema": { "type": "text" } } }, "description": "Response can either be a text/plain base64 encoded body\nor 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": [ "Browser REST APIs" ] } }, "/search": { "post": { "definitions": {}, "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" } } ], "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": "#/definitions/SearchResponseData" }, "totalResults": { "type": "number" }, "error": { "type": "string" }, "errorCode": { "$ref": "#/definitions/SearchFailureCode" }, "unresponsiveEngines": { "type": "array", "items": { "$ref": "#/definitions/UnresponsiveEngine" } } }, "additionalProperties": false, "required": [ "data", "success", "totalResults" ], "definitions": { "SearchResponseData": { "type": "object", "properties": { "web": { "type": "array", "items": { "$ref": "#/definitions/WebSearchResult" } }, "news": { "type": "array", "items": { "$ref": "#/definitions/NewsSearchResult" } }, "images": { "type": "array", "items": { "$ref": "#/definitions/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 }, "SearchFailureCode": { "enum": [ "no_results", "upstream_timeout", "upstream_unavailable" ], "type": "string" }, "UnresponsiveEngine": { "type": "object", "properties": { "engine": { "type": "string" }, "reason": { "$ref": "#/definitions/UnresponsiveEngineReason" } }, "additionalProperties": false, "required": [ "engine", "reason" ] }, "UnresponsiveEngineReason": { "enum": [ "access_denied", "captcha", "rate_limited", "timeout", "unknown" ], "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": "/search", "tags": [ "Browser REST APIs" ] } }, "/session": { "post": { "definitions": {}, "description": "Creates a new browser session with the specified parameters. The session can be used for persistent browser connections\nwith well-defined lifetimes and reconnection semantics.", "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\nand all files and processes will be cleaned up. Must be a non-negative number. Hosted Cloud accepts\n0 as the plan's maximum retention and rejects values above that maximum.", "type": "number" }, "processKeepAlive": { "description": "An optional time, in milliseconds, to keep the underlying browser process alive after a connection to the session closes.\nIf a connection happens within the keep-alive window, the browser process will remain running and the session can be reconnected to.\nIf a connection happens after the keep-alive window has expired, a new browser process will be launched for the session, with the prior\nsession 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" }, "blockAdsInclude": { "description": "Restrict blockAds to a specific set of uBlock ruleset ids (comma-separated\nlist or JSON array). Only applies when `blockAds` is true. Fewer rulesets\nmeans a faster browser launch under load; omit to load the full default set.", "type": "string" }, "headless": { "description": "Whether the browser should be launched in headless mode.\nIgnored if `stealth` is true, defaults to \"true\".", "type": "boolean" }, "defaultViewport": { "description": "The default viewport for pages in non-stealth sessions. Ignored when\n`stealth` is true or `browser` is \"stealth\". Takes precedence over the\nconnect URL's launch.defaultViewport, including after a browser restart.", "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" ] }, "args": { "description": "An array of command-line arguments to pass to the browser.\nDefaults to an empty array.", "type": "array", "items": { "type": "string" } }, "browser": { "description": "The type of browser to use for the session.\n'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\nrequired special handling in order to work correctly or unblock.\nThis is not required, but can be useful or required for certain sites.", "type": "string" }, "proxy": { "description": "Proxy Parameters for the session if desired.\nIf 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.\nWhen 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.\nExtensions must be previously uploaded to the browserless extension storage.\nThis allows sessions to start with extensions pre-loaded without specifying\nthem 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.\nThe profile's cookies, localStorage, and IndexedDB entries are injected via\nCDP before your code runs. sessionStorage is intentionally not restored —\nit is tab-scoped and stale values break OAuth/CSRF flows. Changes during\nthe session do not affect the source profile.", "type": "string" }, "integrationId": { "description": "Optional 1Password integration id (op_int_…) or label. Browserless.loadSecret can\nresolve credentials from this integration during the session. Validated at\nsession creation; a missing or expired integration rejects the request.", "type": "string" }, "credentials": { "description": "Maps caller aliases to 1Password op:// references, e.g.\n{ \"password\": \"op://Prod/GitHub/password\" }. Reference strings are not\nsecret; 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.\nCannot widen it — the effective list is the intersection of the two.", "type": "array", "items": { "type": "string" } }, "label": { "description": "An optional, caller-supplied label for the session. Stored on the session\nrecord for the caller's own bookkeeping; does not affect behavior.", "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.\nThis 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": [ "Management REST APIs", "Browser REST APIs" ] } }, "/session/*": { "delete": { "definitions": {}, "description": "Deletes a session and its associated data. This will immediately terminate any active connections to the session if \"force\" is applied.\n\nQuery Parameters:\n- force (optional): If true, forces deletion even if the session has active connections", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "force", "schema": { "description": "Whether to force the deletion of the session even if it has active connections.\nDefaults to false.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": [ "Management REST APIs", "Browser REST APIs" ] } }, "/smart-scrape": { "post": { "definitions": {}, "description": "Intelligently scrapes a URL using cascading strategies (HTTP fetch, proxy, headless browser, etc).", "parameters": [ { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "OS to emulate: `windows`/`macos`/`linux`/`android`. Omitted → native Linux\nwith no device profile; an explicit `linux` still gets one." } }, { "in": "query", "name": "profile", "schema": { "description": "Optional name of an authentication profile to hydrate into the browser\nbefore scraping. The profile's cookies, localStorage, and IndexedDB\nentries are loaded into the session before navigation. Forces the\nbrowser 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" } } ], "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\nstrings such as `[\"markdown\", \"screenshot\"]`. When `screenshot` or `pdf`\nis included, a browser strategy is forced.\nMirrors the Firecrawl \"formats\" convention.\n\n- `markdown` – page content converted to markdown\n- `html` – cleaned HTML (returned by default in `content`, this is a no-op convenience value)\n- `rawText` – DOM text with script, style, and noscript elements removed and whitespace collapsed; PDF targets return extracted text\n- `screenshot` – full-page screenshot as base64-encoded PNG (forces browser strategy)\n- `pdf` – PDF of the page as base64-encoded string (forces browser strategy)\n- `links` – list of links extracted from the page", "default": [ "html" ], "type": "array", "items": { "enum": [ "html", "links", "markdown", "pdf", "rawText", "screenshot" ], "type": "string" } }, "actions": { "description": "Browser actions to run in order before the final page is captured. The\nsupported action types are `wait`, `click`, `write`, `scroll`, `scrape`,\nand `executeJavascript`. A maximum of 20 actions is allowed. Detailed,\nindex-aware validation is performed by the route so the generated schema\nintentionally leaves each array entry permissive.\n\n- `wait` accepts exactly one of `milliseconds` or `selector`\n- `click` accepts a non-empty `selector`\n- `write` accepts a non-empty `selector` and string `text`\n- `scroll` optionally accepts a `selector`\n- `scrape` captures the current page URL and HTML\n- `executeJavascript` accepts a non-empty `script` up to 10,000 characters\n\n`wait`, `click`, `write`, `scroll`, and `executeJavascript` may include a\npositive `timeout` of at most 30,000 milliseconds (default 10,000).\nEvery action and the final page settle share the request timeout budget.\n\nAn empty array is accepted as a no-op. Use a trailing newline in\n`write.text` to submit a form. Screenshots and PDFs are requested through\ntop-level `formats` and capture the final page after all actions run.", "maxItems": 20, "type": "array", "items": {} }, "proxy": { "description": "The proxy network to route the scrape through. Defaults to `residential`.\nUse `datacenter` for the cheaper datacenter pool.", "enum": [ "datacenter", "residential" ], "type": "string" }, "onlyMainContent": { "description": "For HTML webpages, extract the main article content, removing navigation,\nheaders, footers, sidebars and other boilerplate from DOM-derived outputs.\nParsed JSON and PDF content are unchanged. Unlike Firecrawl, this defaults\nto false; when enabled, the HTML format contains the extracted HTML.", "default": false, "type": "boolean" }, "includeTags": { "description": "CSS selectors to keep in HTML webpage outputs. Malformed entries are\nignored; if no selector matches, unfiltered content is returned. Mutually\nexclusive with excludeTags and onlyMainContent.", "maxItems": 100, "type": "array", "items": { "type": "string" } }, "excludeTags": { "description": "CSS selectors to remove from HTML webpage outputs. Malformed entries are\nignored. Mutually exclusive with includeTags.", "maxItems": 100, "type": "array", "items": { "type": "string" } }, "headers": { "description": "Custom request headers sent to the target. host, authorization,\nproxy-authorization, cookie, set-cookie, x-forwarded-for, x-real-ip, and\nforwarded are removed.", "type": "object", "additionalProperties": { "type": "string" } }, "waitFor": { "description": "Milliseconds to wait after page load. Clamped to [0, 30000]; positive\nvalues force a browser strategy.", "default": 0, "type": "number" }, "strategyCache": { "description": "Whether to use and update the remembered winning strategy for this host.\nDefaults to `true`. Set to `false` to bypass both reads and writes for this\nrequest.", "default": true, "type": "boolean" } }, "type": "object", "required": [ "url" ] } } } }, "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 is extracted text for PDF targets, a string for HTML content, or a parsed object for JSON. Will be null if the scrape was unsuccessful.", "anyOf": [ { "$ref": "#/definitions/Record%3Cstring%2Cunknown%3E" }, { "type": "string" } ] }, "contentType": { "description": "The content type returned by the target, or null if the scrape was unsuccessful or unavailable. JSON content is parsed into an object; PDF content is extracted into text.", "type": "string" }, "headers": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "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\n`formats`. On a successful scrape this is the scraped page; on a captcha /\nanti-bot failure (`ok:false`) it is a best-effort debug capture of the\nblocking page. Null otherwise.", "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. For PDF targets, this is extracted page text joined with blank lines.", "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" } }, "actions": { "anyOf": [ { "description": "Values captured by `scrape` and `executeJavascript` actions, or null when\nactions were omitted, empty, or the scrape failed.", "type": "object", "properties": { "scrapes": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "html": { "type": "string" } }, "additionalProperties": false, "required": [ "html", "url" ] } }, "javascriptReturns": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": [ "string", "null" ] } }, "additionalProperties": false, "required": [ "type", "value" ] } } }, "additionalProperties": false, "required": [ "javascriptReturns", "scrapes" ] }, { "type": "null" } ] }, "rawText": { "description": "DOM text with scripts/styles removed and whitespace collapsed, or extracted PDF text.", "type": "string" }, "metadata": { "description": "Page metadata on success, or null when scraping fails.", "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "language": { "type": "string" }, "sourceURL": { "type": "string" }, "statusCode": { "type": "number" } }, "additionalProperties": false, "required": [ "description", "language", "sourceURL", "statusCode", "title" ] } }, "additionalProperties": false, "required": [ "actions", "attempted", "content", "contentType", "headers", "links", "markdown", "message", "metadata", "ok", "pdf", "rawText", "screenshot", "statusCode", "strategy" ], "definitions": { "Record": { "type": "object", "additionalProperties": false }, "Record": { "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": [ "Browser REST APIs" ] } }, "/stealth/bql?(/*)": { "post": { "definitions": {}, "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\nauthorities) 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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "description": "Whether to automatically block cookie consent modals and popups.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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.\nWhen true, actions like typing and clicking will have randomized delays.", "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "description": "Whether to enable session recording for replay.\nWhen true, the session will be recorded and can be replayed later.", "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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" ] }, "get": { "definitions": {}, "description": "WebSocket endpoint for BrowserQL. Connect to establish a persistent browser\nsession, then send multiple GraphQL operations as JSON messages. The browser\nand page state persist across all messages for the connection duration.\n\nMessages use the same JSON format as the HTTP POST endpoint:\nSend: { \"query\": \"mutation { goto(url: \\\"..\\\") { status } }\", \"variables\": {} }\nReceive: { \"data\": { \"goto\": { \"status\": 200 } } }", "parameters": [ { "in": "query", "name": "acceptInsecureCerts", "schema": { "description": "Whether to ignore TLS certificate errors (e.g. self-signed or untrusted\nauthorities) 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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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 (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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" ] } }, "/chrome/bql?(/*)": { "post": { "definitions": {}, "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\nauthorities) 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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "description": "Whether to automatically block cookie consent modals and popups.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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.\nWhen true, actions like typing and clicking will have randomized delays.", "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "description": "Whether to enable session recording for replay.\nWhen true, the session will be recorded and can be replayed later.", "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": [ "Browser REST APIs" ] }, "get": { "definitions": {}, "description": "WebSocket endpoint for BrowserQL. Connect to establish a persistent browser\nsession, then send multiple GraphQL operations as JSON messages. The browser\nand page state persist across all messages for the connection duration.\n\nMessages use the same JSON format as the HTTP POST endpoint:\nSend: { \"query\": \"mutation { goto(url: \\\"..\\\") { status } }\", \"variables\": {} }\nReceive: { \"data\": { \"goto\": { \"status\": 200 } } }", "parameters": [ { "in": "query", "name": "acceptInsecureCerts", "schema": { "description": "Whether to ignore TLS certificate errors (e.g. self-signed or untrusted\nauthorities) 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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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 (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": [ "Browser WebSocket APIs" ] } }, "/chromium/bql?(/*)": { "post": { "definitions": {}, "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\nauthorities) 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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "description": "Whether to automatically block cookie consent modals and popups.", "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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.\nWhen true, actions like typing and clicking will have randomized delays.", "type": "boolean" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "description": "Whether to enable session recording for replay.\nWhen true, the session will be recorded and can be replayed later.", "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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" ] }, "get": { "definitions": {}, "description": "WebSocket endpoint for BrowserQL. Connect to establish a persistent browser\nsession, then send multiple GraphQL operations as JSON messages. The browser\nand page state persist across all messages for the connection duration.\n\nMessages use the same JSON format as the HTTP POST endpoint:\nSend: { \"query\": \"mutation { goto(url: \\\"..\\\") { status } }\", \"variables\": {} }\nReceive: { \"data\": { \"goto\": { \"status\": 200 } } }", "parameters": [ { "in": "query", "name": "acceptInsecureCerts", "schema": { "description": "Whether to ignore TLS certificate errors (e.g. self-signed or untrusted\nauthorities) 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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for the mobile persona (emulationOs=android): a device slug such\nas 'pixel-8', 'pixel-8-pro', 'galaxy-s23', 'galaxy-s23-ultra'. Drives the\nUA-CH model/version, viewport/DPR, touch points, cores, memory and GPU string.\nOmit to auto-pick a device seeded per session (stable per identity, spread\nacross the fleet; an unknown slug does the same). Requires emulationOs=android\non a stealth request — sent otherwise, the request is rejected with 400.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for the session: 'windows', 'macos', or 'linux'. When set, the\nsession runs the full per-platform stealth stack (User-Agent, UA Client\nHints, navigator.platform, GPU, fonts, and media/speech/audio fingerprints)\n— the same stack the /stealth routes use. Omit for the native (Linux) host\nidentity." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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 (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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" ] } }, "/session/bql/*": { "post": { "definitions": {}, "description": "> Executes BrowserQL queries against an existing session.\n\nBrowserQL is a GraphQL-based query language for browser automation that allows you to interact with web pages using a declarative syntax.\nQueries 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 nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options for the browser, either as a JSON object or a JSON string.\nIncludes options like `headless`, `args`, `defaultViewport`, etc.\nMust be either JSON object, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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 GraphQL query string to execute against the browser session.\n\nExample queries:\n- Get browser info: `query { version browser }`\n- Navigate and get content: `mutation { goto(url: \"https://example.com\") { status } title { title } url { url } }`\n- 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 } }`\n- 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.\n\nExample: `{ \"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.\nOptional - 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": "#/definitions/Record%3Cstring%2Cany%3E", "description": "The GraphQL response data. Contains the result of the executed query.\nStructure depends on the specific query executed.\n\nExample responses:\n- Navigation + Title + Element: `{ \"goto\": { \"status\": 200 }, \"title\": { \"title\": \"Example Domain\" }, \"querySelector\": { \"innerHTML\": \"Example Domain\" } }`\n- Multiple elements: `{ \"querySelectorAll\": [{ \"innerHTML\": \"Item 1\" }, { \"innerHTML\": \"Item 2\" }] }`\n- Screenshot: `{ \"screenshot\": { \"data\": \"base64encodedimage\", \"type\": \"png\" } }`\n- PDF: `{ \"pdf\": { \"data\": \"base64encodedpdf\" } }`\n- System info: `{ \"version\": \"1.0.0\", \"browser\": \"Chrome/120.0.0.0\" }`\n- Form interaction: `{ \"type\": { \"success\": true }, \"click\": { \"success\": true } }`" }, "errors": { "description": "Array of GraphQL errors, if any occurred during query execution.\nOnly 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": { "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": [ "Management REST APIs", "Browser REST APIs" ] } }, "/chromium/agent/capabilities": { "get": { "definitions": {}, "description": "Returns the versioned capabilities declared by the Chromium agent route.\nSupply the intended route query parameters so authentication and plan checks\ncan reject unsupported combinations before a browser is allocated.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for mobile personas (emulationOs=android), e.g. \"pixel-8\",\n\"galaxy-s23\". Omit to auto-pick a device seeded per session (stable per\nidentity, spread across the fleet); an unknown slug does the same.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux | android." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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 (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "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.\nAccepts 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": { "version": { "type": "number", "const": 1, "default": 1 }, "route": { "type": "string", "const": "/chromium/agent" }, "capabilities": { "type": "object", "properties": { "vision": { "type": "object", "properties": { "available": { "type": "boolean", "const": true, "default": true }, "primitives": { "type": "array", "items": [ { "type": "string", "const": "screenshot" }, { "type": "string", "const": "viewport" } ], "minItems": 2, "maxItems": 2, "default": [ "screenshot", "viewport" ] }, "availableAt": { "type": "array", "items": [ { "type": "string", "const": "/chromium/agent" } ], "minItems": 1, "maxItems": 1 } }, "additionalProperties": false, "required": [ "available", "availableAt", "primitives" ] }, "os-spoofing": { "type": "object", "properties": { "available": { "type": "boolean", "const": true, "default": true }, "queryParameters": { "type": "array", "items": [ { "type": "string", "const": "emulationOs" } ], "minItems": 1, "maxItems": 1, "default": [ "emulationOs" ] }, "availableAt": { "type": "array", "items": [ { "type": "string", "const": "/chromium/agent" }, { "type": "string", "const": "/stealth/bql" } ], "minItems": 2, "maxItems": 2 } }, "additionalProperties": false, "required": [ "available", "availableAt", "queryParameters" ] }, "datacenter-proxy": { "type": "object", "properties": { "available": { "type": "boolean", "const": true, "default": true }, "queryParameters": { "type": "array", "items": [ { "type": "string", "const": "proxy" } ], "minItems": 1, "maxItems": 1, "default": [ "proxy" ] }, "values": { "type": "array", "items": [ { "type": "string", "const": "datacenter" } ], "minItems": 1, "maxItems": 1, "default": [ "datacenter" ] }, "availableAt": { "type": "array", "items": [ { "type": "string", "const": "/chromium/agent" }, { "type": "string", "const": "/stealth/bql" } ], "minItems": 2, "maxItems": 2 } }, "additionalProperties": false, "required": [ "available", "availableAt", "queryParameters", "values" ] }, "secret-capture": { "type": "object", "properties": { "available": { "type": "boolean", "const": true, "default": true }, "primitives": { "type": "array", "items": [ { "type": "string", "const": "loadSecret" }, { "type": "string", "const": "saveSecret" }, { "type": "string", "const": "clearSecrets" }, { "type": "string", "const": "goto" }, { "type": "string", "const": "screenshot" } ], "minItems": 5, "maxItems": 5, "default": [ "loadSecret", "saveSecret", "clearSecrets", "goto", "screenshot" ] }, "ordering": { "type": "string", "const": "Run screenshots before loadSecret, or run clearSecrets or a top-frame navigation before capturing. saveSecret is not gated by the capture gate and may run at any point.", "default": "Run screenshots before loadSecret, or run clearSecrets or a top-frame navigation before capturing. saveSecret is not gated by the capture gate and may run at any point." }, "availableAt": { "type": "array", "items": [ { "type": "string", "const": "/chromium/agent" } ], "minItems": 1, "maxItems": 1 } }, "additionalProperties": false, "required": [ "available", "availableAt", "ordering", "primitives" ] } }, "additionalProperties": false, "required": [ "datacenter-proxy", "os-spoofing", "secret-capture", "vision" ] } }, "additionalProperties": false, "required": [ "capabilities", "route", "version" ], "$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/agent/capabilities", "tags": [ "Management REST APIs", "Browser REST APIs" ] } }, "/agent/run/*/continue": { "post": { "definitions": {}, "description": "Continue a multi-turn agent run with a follow-up task. Not enabled in v1.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "query": { "description": "Follow-up task for the next turn.", "type": "string" } }, "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": "/agent/run/*/continue", "tags": [ "Browser REST APIs" ] } }, "/agent/run/*": { "delete": { "definitions": {}, "description": "Cancel an active agent run (including needs_human), aborting the in-flight turn, or delete a terminal one.", "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": "/agent/run/*", "tags": [ "Browser REST APIs" ] }, "get": { "definitions": {}, "description": "Poll an agent run: its status, the latest turn result and streamed step rationales, and the full turn transcript.", "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": "/agent/run/*", "tags": [ "Browser REST APIs" ] } }, "/agent/run": { "get": { "definitions": {}, "description": "List the caller's agent runs, newest first, with cursor pagination.", "parameters": [ { "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from a previous response.", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "description": "Page size, 1-100.", "type": "number" } }, { "in": "query", "name": "status", "schema": { "description": "Filter by run status.", "type": "string" } }, { "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": "/agent/run", "tags": [ "Browser REST APIs" ] }, "post": { "definitions": {}, "description": "Start an asynchronous AI agent run: a managed agent drives a real browser against a natural-language task and returns a structured JSON result. Returns a run ID to poll via GET /agent/run/{id}.", "parameters": [ { "in": "query", "name": "token", "schema": { "description": "The API token for authenticating the request.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "query": { "description": "Natural-language task for the agent. Minimum 10 characters.", "type": "string" }, "timeout": { "description": "Per-turn timeout in ms, clamped to [10000, 900000] (15-min hard cap).", "type": "number" }, "onHumanNeeded": { "description": "Pause for human login/MFA in the same session. Default: fail. Does not extend timeout.", "enum": [ "fail", "pause" ], "type": "string" }, "webhook": { "description": "Optional webhook for terminal states and human handoffs.", "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "enum": [ "failed", "needs_human", "succeeded" ], "type": "string" } } }, "additionalProperties": false, "required": [ "url" ] }, "responseSchema": { "description": "Best-effort JSON schema for the agent's final answer.", "type": "object", "properties": {}, "additionalProperties": true }, "maxSteps": { "description": "Soft cap on browser tool calls. Default 60, hard cap 90.", "type": "number" }, "allowedDomains": { "description": "Navigation allowlist.", "type": "array", "items": { "type": "string" } }, "startUrl": { "description": "First navigation target.", "type": "string" }, "proxy": { "description": "Route browsing through a residential or datacenter proxy. Best-effort like\nthe other hints below: injected into the agent's prompt, not enforced.", "enum": [ "datacenter", "residential" ], "type": "string" }, "proxyCountry": { "description": "Two-letter country code for the proxy exit (e.g. `US`).", "type": "string" }, "stealth": { "description": "Ask the agent to use stealth / anti-bot-detection mode.", "type": "boolean" }, "solveCaptchas": { "description": "Ask the agent to solve CAPTCHAs it encounters.", "type": "boolean" }, "profile": { "description": "Name of a saved authentication profile to reuse.", "type": "string" }, "replay": { "description": "Opt in to recording the run as a session replay, listed in the account\ndashboard. Enforced on the worker-owned session, not suggested to the model.\nRuns falling back to an MCP-owned session are not recorded.", "type": "boolean" }, "formats": { "description": "Page captures to return with the result, taken from the agent's current\ntab when the run ends. Omit for none.", "type": "array", "items": { "enum": [ "html", "links", "markdown", "screenshot" ], "type": "string" } } }, "type": "object", "required": [ "query" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": false, "required": [ "id", "status" ], "$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": "/agent/run", "tags": [ "Browser REST APIs" ] } }, "/crawl/*": { "delete": { "definitions": {}, "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": [ "Browser REST APIs" ] }, "get": { "definitions": {}, "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": "#/definitions/CrawlStatus" }, "total": { "type": "number" }, "completed": { "type": "number" }, "failed": { "type": "number" }, "expiresAt": { "type": "string" }, "next": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/definitions/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": "#/definitions/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": [ "Browser REST APIs" ] } }, "/crawl": { "get": { "definitions": {}, "description": "List all crawl jobs owned by the authenticated account (or, for keys not yet mapped to an account, the 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": "#/definitions/CrawlListItem" } }, "nextCursor": { "type": "string" } }, "additionalProperties": false, "required": [ "crawls", "nextCursor" ], "definitions": { "CrawlListItem": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "$ref": "#/definitions/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": [ "Browser REST APIs" ] }, "post": { "definitions": {}, "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\nbefore each page is scraped. The profile's cookies, localStorage, and\nIndexedDB entries are loaded into the session before navigation. Forces\nthe 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)\nor `\"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" ] } } } }, "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": [ "Browser REST APIs" ] } }, "/skills": { "get": { "definitions": {}, "description": "Returns the browser-automation skills known for a site: tuned, site-specific\nrecipes an agent should follow instead of planning its own steps.\n\"domain\" is required; \"task\" narrows the result to a single skill slug.\nReturns an empty array when no skill is known for the domain.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "domain", "schema": { "description": "Hostname to look skills up for, e.g. \"airbnb.com\". A scheme, port or\n\"www.\" prefix is accepted and normalized away.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "task", "schema": { "description": "Optional skill slug, e.g. \"search-listings\". Omit to get every skill\nknown for the domain.", "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": "#/definitions/SkillResponse" }, "definitions": { "SkillResponse": { "description": "The public shape: no `source`, which carries token_hash / sessionId.", "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "task": { "type": "string" }, "title": { "type": "string" }, "skill_md": { "type": "string" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "additionalProperties": false, "required": [ "created_at", "domain", "id", "skill_md", "task", "title", "updated_at", "version" ] } }, "$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": "/skills", "tags": [ "Management REST APIs" ] } }, "/profile": { "post": { "definitions": {}, "description": "Launches a temporary browser session for creating an authenticated profile.\nConnect via the returned WebSocket URL, authenticate in the browser,\nthen call Browserless.saveProfile via CDP to capture and persist the auth state.\nThe profile is NOT saved automatically — you must explicitly call\nBrowserless.saveProfile before disconnecting. The session expires after 10 minutes\nor your plan's session limit, whichever comes first. Free sessions are capped at\ntwo minutes; higher-tier plans retain the 10-minute maximum.\n\n**Note:** This endpoint is also available at: `/management/profile` for backwards compatibility.", "parameters": [ { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "OS persona to preserve while authoring the profile." } }, { "in": "query", "name": "timeout", "schema": { "description": "Maximum duration of the temporary profile-creation session, in\nmilliseconds. The effective duration is capped by the smaller of 10\nminutes and your plan's session limit.", "type": "number" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "A user-visible name for the profile.\nMust 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 (op_int_…) or label. The profile-authoring session\ncan 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": [ "Management REST APIs" ] }, "delete": { "definitions": {}, "description": "Removes selected sites and their cookies, localStorage and IndexedDB from a saved profile.\n\n**Note:** This endpoint is also available at: `/management/profile` for backwards compatibility.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "domains": { "description": "Exact sites to remove, without cascading to subdomains.", "type": "array", "items": { "type": "string" } } }, "type": "object", "required": [ "domains", "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" }, "captureSettings": { "$ref": "#/definitions/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/definitions/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "definitions": { "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/definitions/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/profile", "tags": [ "Management REST APIs" ] } }, "/profile/*": { "delete": { "definitions": {}, "description": "Deletes an authentication profile and its captured state.\nThe profile name is the URL-encoded path segment after \"/profile/\".\nReturns 404 if no profile with that name exists for this token.\n\n**Note:** This endpoint is also available at: `/management/profile/*` for backwards compatibility.", "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": [ "Management REST APIs" ] }, "get": { "definitions": {}, "description": "Returns metadata for a specific authentication profile.\nThe profile name is the URL-encoded path segment after \"/profile/\".\nReturns 404 if no profile with that name exists for this token.\n\n**Note:** This endpoint is also available at: `/management/profile/*` for backwards compatibility.", "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" }, "captureSettings": { "$ref": "#/definitions/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/definitions/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "definitions": { "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/definitions/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/profile/*", "tags": [ "Management REST APIs" ] }, "put": { "definitions": {}, "description": "Renames an authentication profile. The new name must be unique per token.\nThe current name is the URL-encoded path segment after \"/profile/\".\nReturns 400 if the new name is already taken, 404 if the source profile is not found.\n\n**Note:** This endpoint is also available at: `/management/profile/*` for backwards compatibility.", "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" }, "captureSettings": { "$ref": "#/definitions/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/definitions/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "definitions": { "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/definitions/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/profile/*", "tags": [ "Management REST APIs" ] } }, "/profile/*/download": { "get": { "definitions": {}, "description": "Downloads the captured authentication state for a specific profile.\nThe profile name is the URL-encoded path segment before \"/download\".\nReturns 404 if no profile with that name exists for this token.\n\n**Note:** This endpoint is also available at: `/profile/.*/download` for backwards compatibility.", "parameters": [], "requestBody": { "content": {} }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cookies": { "type": "array", "items": { "$ref": "#/definitions/ProfileCookie" } }, "origins": { "type": "array", "items": { "$ref": "#/definitions/DownloadProfileOriginStorage" } } }, "additionalProperties": false, "required": [ "cookies", "origins" ], "definitions": { "ProfileCookie": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "string" }, "expires": { "type": "number" }, "size": { "type": "number" }, "httpOnly": { "type": "boolean" }, "secure": { "type": "boolean" }, "session": { "type": "boolean" }, "sameSite": { "enum": [ "Lax", "None", "Strict" ], "type": "string" }, "sourceScheme": { "enum": [ "NonSecure", "Secure", "Unset" ], "type": "string" }, "sourcePort": { "type": "number" } }, "additionalProperties": false, "required": [ "domain", "expires", "httpOnly", "name", "path", "secure", "session", "size", "value" ] }, "DownloadProfileOriginStorage": { "type": "object", "properties": { "origin": { "type": "string" }, "localStorage": { "$ref": "#/definitions/DownloadProfileLocalStorage" }, "indexedDBs": { "type": "array", "items": { "$ref": "#/definitions/DownloadProfileIndexedDB" } } }, "additionalProperties": false, "required": [ "localStorage", "origin" ] }, "DownloadProfileLocalStorage": { "type": "object", "additionalProperties": { "type": "string" } }, "DownloadProfileIndexedDB": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "number" }, "objectStores": { "type": "array", "items": { "$ref": "#/definitions/DownloadProfileIndexedDBObjectStore" } } }, "additionalProperties": false, "required": [ "name", "objectStores", "version" ] }, "DownloadProfileIndexedDBObjectStore": { "type": "object", "properties": { "name": { "type": "string" }, "keyPath": { "anyOf": [ { "$ref": "#/definitions/DownloadProfileNullableKeyPath" }, { "type": "null" } ] }, "autoIncrement": { "type": "boolean" }, "entries": { "type": "array", "items": { "$ref": "#/definitions/ProfileIndexedDBEntry" } }, "indexes": { "type": "array", "items": { "$ref": "#/definitions/DownloadProfileIndexedDBIndex" } } }, "additionalProperties": false, "required": [ "autoIncrement", "entries", "indexes", "keyPath", "name" ] }, "DownloadProfileNullableKeyPath": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "ProfileIndexedDBEntry": { "type": "object", "properties": { "key": {}, "value": {} }, "additionalProperties": false, "required": [ "key", "value" ] }, "DownloadProfileIndexedDBIndex": { "type": "object", "properties": { "name": { "type": "string" }, "keyPath": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "unique": { "type": "boolean" }, "multiEntry": { "type": "boolean" } }, "additionalProperties": false, "required": [ "keyPath", "multiEntry", "name", "unique" ] } }, "$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/*/download", "tags": [ "Management REST APIs" ] } }, "/profiles": { "get": { "definitions": {}, "description": "Lists authentication profiles owned by the requesting token.\nPaginated via \"limit\" (default 100, capped at 1000) and \"offset\" (default 0).\nReturns an empty array if the token has no profiles.\n\n**Note:** This endpoint is also available at: `/management/profiles` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/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.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "#/definitions/ProfileResponse" }, "definitions": { "ProfileResponse": { "description": "Public-facing profile response returned by HTTP routes.\nOmits 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" }, "captureSettings": { "$ref": "#/definitions/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/definitions/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ] }, "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/definitions/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/profiles", "tags": [ "Management REST APIs" ] } }, "/profile/refresh": { "post": { "definitions": {}, "description": "Replaces the state of an existing authentication profile in place.\nThe \"name\" must already exist for the requesting token. Counts of any\ndropped 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\nrequesting token.", "type": "string" }, "state": { "description": "Pre-captured authentication state. Same shape as `POST /profile/upload`." }, "captureSettings": { "$ref": "#/definitions/RefreshCaptureSettingsPayload", "description": "Capture inputs this refresh ran with. Omit the key to leave the stored settings\nuntouched — which is what an older CLI does. An object that survives validation\nREPLACES the stored one wholesale — it is not a patch, so a partial payload drops\nthe members it omits.\n\nAn object that validates down to nothing — `{}`, or one carrying only\n`onlyDomains: []` / `keepDomains: []` — is treated as if the key were omitted:\n200, stored settings untouched. `excludeDomains: []` is the deliberate exception:\nit survives, so the payload DOES replace the stored object and drops every member\nit omits. It records \"captured with no exclusions\", which a later flagless refresh\nreplays instead of re-reading the refreshing machine's own config." } }, "type": "object", "required": [ "name", "state" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "diagnostics": { "$ref": "#/definitions/RefreshResponseDiagnostics", "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped 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" }, "captureSettings": { "$ref": "#/definitions/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/definitions/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "diagnostics", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "definitions": { "RefreshResponseDiagnostics": { "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped 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" }, "skippedMalformedLocalStorageEntries": { "description": "localStorage entries dropped because names or values were not strings.", "type": "number" }, "skippedMalformedIdbIndexes": { "description": "IndexedDB indexes dropped because required fields were malformed.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbIndexes", "skippedMalformedIdbStores", "skippedMalformedLocalStorageEntries", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] }, "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/definitions/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/profile/refresh", "tags": [ "Management REST APIs" ] } }, "/profile/upload": { "post": { "definitions": {}, "description": "Creates a new authentication profile from a pre-captured \"state\" payload\n(cookies plus per-origin localStorage and IndexedDB). The \"name\" must be\nunique per token. Counts of any dropped or truncated entries are\nsurfaced 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 —\n`cookies` (browser cookies) and `origins` (per-origin localStorage and\nIndexedDB)." }, "captureSettings": { "$ref": "#/definitions/UploadCaptureSettingsPayload", "description": "Capture inputs the CLI ran with, stored so a later `browserless profile refresh`\ncan replay them without flags. Optional — an older CLI omits it. This route is a\nstrict create, so there is nothing to preserve: the profile is created with these\nsettings, or with none.\n\nAn object that validates down to nothing — `{}`, or one carrying only\n`onlyDomains: []` / `keepDomains: []` — is stored as `null`, the same as omitting\nthe key. `excludeDomains: []` is the deliberate exception: it survives and records\n\"captured with no exclusions\", which a later flagless refresh replays instead of\nre-reading the refreshing machine's own config." } }, "type": "object", "required": [ "name", "state" ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "diagnostics": { "$ref": "#/definitions/UploadResponseDiagnostics", "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped 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" }, "captureSettings": { "$ref": "#/definitions/ProfileCaptureSettings", "description": "Capture inputs the CLI used, or null for profiles not created by the CLI. The UI\nderives no capture flag from these; it uses any non-empty object to stamp the CLI\nbadge and show a read-only summary, and reads `browser`/`profile` specifically to\ndecide whether its refresh command needs placeholders for them. The CLI reads the\nrest itself and decides the exclusion behaviour from `excludeDomains`." }, "domainAuth": { "description": "Per-domain auth status + expiry for the saved logins in this profile, with\nstatus classified at read time (valid / expiring_soon / expired / unknown).\nEmpty for profiles saved before this feature, until their next capture,\nupload, or refresh. Never contains a cookie value.", "type": "array", "items": { "$ref": "#/definitions/ProfileDomainAuth" } }, "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": [ "captureSettings", "cookieCount", "createdAt", "diagnostics", "domainAuth", "id", "lastUsedAt", "name", "originCount", "updatedAt" ], "definitions": { "UploadResponseDiagnostics": { "description": "Per-entry counts of cookies, origins, and IndexedDB items the server\ndropped 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" }, "skippedMalformedLocalStorageEntries": { "description": "localStorage entries dropped because names or values were not strings.", "type": "number" }, "skippedMalformedIdbIndexes": { "description": "IndexedDB indexes dropped because required fields were malformed.", "type": "number" } }, "additionalProperties": false, "required": [ "skippedMalformedCookies", "skippedMalformedIdbDatabases", "skippedMalformedIdbIndexes", "skippedMalformedIdbStores", "skippedMalformedLocalStorageEntries", "skippedMalformedOrigins", "skippedPrivateCookies", "skippedPrivateOrigins", "truncatedIdbDatabases", "truncatedIdbEntries", "truncatedOrigins" ] }, "ProfileCaptureSettings": { "description": "Capture inputs the CLI ran with, so a later `profile refresh` can replay them\nwithout flags. Null for the CDP saveProfile path and any future non-CLI creator.\nNever holds the token, and omits server/region because a stale stored region\nis a guaranteed 404.", "type": "object", "properties": { "browser": { "description": "Raw `--browser` value.", "type": "string" }, "profile": { "description": "Raw `--profile` value (source profile directory or display name).", "type": "string" }, "excludeDomains": { "description": "Effective merged exclusion list. `[]` is meaningful — \"captured with no\nexclusions\" — and distinct from absent, which means \"unknown\".", "type": "array", "items": { "type": "string" } }, "onlyDomains": { "description": "Normalized `--only-domain` hostnames, deduped and capped — not merged with local config.", "type": "array", "items": { "type": "string" } }, "keepDomains": { "description": "Normalized `--keep-domain` hostnames, same normalization, no merge.", "type": "array", "items": { "type": "string" } }, "autoFit": { "description": "Whether `--auto-fit` was used.", "type": "boolean" }, "passwordStore": { "description": "Raw `--password-store` value. Linux only.", "type": "string" }, "cliVersion": { "description": "CLI version that produced these settings, for drift diagnosis.", "type": "string" } }, "additionalProperties": false }, "ProfileDomainAuth": { "description": "Response shape: the stored snapshot plus its read-time status.", "type": "object", "properties": { "domain": { "type": "string" }, "status": { "$ref": "#/definitions/DomainAuthStatus" }, "expiresAt": { "type": "string" } }, "additionalProperties": false, "required": [ "domain", "expiresAt", "status" ] }, "DomainAuthStatus": { "description": "Per-domain auth status, computed at read time from a stored absolute expiry.", "enum": [ "expired", "expiring_soon", "unknown", "valid" ], "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": "/profile/upload", "tags": [ "Management REST APIs" ] } }, "/integrations/onepassword/*/audit": { "get": { "definitions": {}, "description": "Lists recent credential activity for a single 1Password integration owned\nby the token, newest first. One entry per Browserless.loadSecret or\nsaveSecret attempt: outcome, error code, the credential reference, and\nnon-secret target metadata. Secret values are never recorded or returned.\nPaginated via \"limit\" (default 100, capped at 1000) and \"offset\" (default 0).\nThe URL-encoded path segment may be an integration id or label. Returns 404\nif no matching integration exists for this token.\n\n**Note:** This endpoint is also available at: `/management/integrations/onepassword/*/audit` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/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.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "#/definitions/OpAuditLogResponse" }, "definitions": { "OpAuditLogResponse": { "description": "Public-facing audit-log entry returned by the audit HTTP route. Omits\ntoken_hash — never includes any token material — and carries the credential\nreference plus non-secret target metadata only.", "type": "object", "properties": { "id": { "description": "Unique audit-entry identifier.", "type": "string" }, "integrationId": { "description": "Integration this credential operation used.", "type": "string" }, "profileId": { "description": "Authentication profile associated with the operation, 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": "#/definitions/OpAuditOutcome", "description": "`success` if filled, `saved` if created, otherwise `failure`." }, "errorCode": { "description": "Error code when the outcome is `failure`, otherwise null.", "type": "string" }, "createdAt": { "description": "ISO timestamp of the operation.", "type": "string" } }, "additionalProperties": false, "required": [ "createdAt", "errorCode", "id", "integrationId", "outcome", "profileId", "secretRef", "targetDescriptor", "targetOrigin", "targetSelector" ] }, "OpAuditOutcome": { "description": "Outcome recorded for a Browserless.loadSecret or saveSecret attempt.", "enum": [ "failure", "saved", "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": [ "Management REST APIs" ] } }, "/integrations/onepassword": { "post": { "definitions": {}, "description": "Registers a 1Password integration for the requesting token. The supplied\nservice-account token is encrypted at rest and is never returned by this or\nany other endpoint. Returns the created integration without any token field.\n\n**Note:** This endpoint is also available at: `/management/integrations/onepassword` for backwards compatibility.", "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\nkind 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.\nOmits internal fields — never includes token_hash or any token material.", "type": "object", "properties": { "vaults": { "description": "Live vault titles, only with includeVaults=true; null when unavailable.", "type": "array", "items": { "type": "string" } }, "id": { "description": "Unique integration identifier.", "type": "string" }, "label": { "description": "User-supplied label. Unique per token.", "type": "string" }, "kind": { "$ref": "#/definitions/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.\nOmits 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": [ "Management REST APIs" ] }, "get": { "definitions": {}, "description": "Lists the 1Password integrations owned by the requesting token. Paginated\nvia \"limit\" (default 100, capped at 1000) and \"offset\" (default 0). Records\nnever include any token material.\nPass includeVaults=true to return live vault titles for the first ten rows per response.\nLater rows and unavailable lookups return null. Paginate with limit=10 and offset to retrieve later titles.\n\n**Note:** This endpoint is also available at: `/management/integrations/onepassword` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "includeVaults", "schema": { "description": "Also return live vault titles. Defaults to false.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/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.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "#/definitions/OpIntegrationResponse" }, "definitions": { "OpIntegrationResponse": { "description": "Public-facing integration response returned by HTTP routes.\nOmits internal fields — never includes token_hash or any token material.", "type": "object", "properties": { "vaults": { "description": "Live vault titles, only with includeVaults=true; null when unavailable.", "type": "array", "items": { "type": "string" } }, "id": { "description": "Unique integration identifier.", "type": "string" }, "label": { "description": "User-supplied label. Unique per token.", "type": "string" }, "kind": { "$ref": "#/definitions/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": [ "Management REST APIs" ] } }, "/integrations/onepassword/*": { "delete": { "definitions": {}, "description": "Deletes a 1Password integration owned by the requesting token. The id or\nlabel is the URL-encoded path segment after \"/integrations/onepassword/\".\nReturns 404 if no matching integration exists for this token. Deleting an\nintegration does not touch any authentication profile.\n\n**Note:** This endpoint is also available at: `/management/integrations/onepassword/*` for backwards compatibility.", "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": [ "Management REST APIs" ] }, "get": { "definitions": {}, "description": "Returns metadata for a specific 1Password integration owned by the token.\nThe id or label is the URL-encoded path segment after\n\"/integrations/onepassword/\". Returns 404 if no integration with that id or\nlabel exists for this token. The response never includes token material.\nPass includeVaults=true to also return each integration's vault titles, looked up live from 1Password (null when unavailable).\n\n**Note:** This endpoint is also available at: `/management/integrations/onepassword/*` for backwards compatibility.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "includeVaults", "schema": { "description": "Also return live vault titles. Defaults to false.", "type": "boolean" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": { "vaults": { "description": "Live vault titles, only with includeVaults=true; null when unavailable.", "type": "array", "items": { "type": "string" } }, "id": { "description": "Unique integration identifier.", "type": "string" }, "label": { "description": "User-supplied label. Unique per token.", "type": "string" }, "kind": { "$ref": "#/definitions/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": [ "Management REST APIs" ] } }, "/integrations/onepassword/autologin/form": { "get": { "definitions": {}, "description": "Returns the selectable references for building an autologin profile: the\n1Password integration's login origins and, per origin, the field labels it\nfills (never values). The integrationId query accepts an id or label. Drives\nthe create-profile form.", "parameters": [ { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Which registered 1Password integration id or label to return items for.", "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "profileName", "schema": { "description": "Recovery only: restrict choices to this tenant-owned saved artifact.", "type": "string" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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" ] } }, "inboxCandidates": { "type": "array", "items": { "$ref": "#/definitions/InboxCandidate" } } }, "additionalProperties": false, "required": [ "domains", "inboxCandidates", "integrationId" ], "definitions": { "InboxCandidate": { "type": "object", "properties": { "vault": { "type": "string" }, "item": { "type": "string" }, "label": { "type": "string" } }, "additionalProperties": false, "required": [ "item", "label", "vault" ] } }, "$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": [ "Management REST APIs" ] } }, "/integrations/onepassword/profile": { "post": { "definitions": {}, "description": "Kicks off an autologin task: a managed agent creates a browser profile by\nlogging into the integration's domains, then saves it. integrationId accepts\nan id or label. Returns a taskId to poll via GET\n/integrations/onepassword/profile/:taskId.", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Name to save the resulting profile under. Unique per token.", "type": "string" }, "integrationId": { "description": "Registered 1Password integration id or label.", "type": "string" }, "recover": { "description": "Refresh an existing owned profile instead of creating a new one.", "type": "boolean" }, "allowedDomains": { "description": "Optional subset of the integration's allowed domains.", "type": "array", "items": { "type": "string" } }, "emailOtp": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string" }, "vault": { "type": "string" }, "item": { "type": "string" } }, "additionalProperties": false, "required": [ "item", "origin", "vault" ] } }, "proxy": { "description": "Optional proxy for the browser session the agent logs in through. Omitted\n→ the run goes direct, so it never bills proxy traffic implicitly.", "type": "object", "properties": { "type": { "enum": [ "datacenter", "residential" ], "type": "string" }, "sticky": { "type": "boolean" }, "country": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "preset": { "type": "string" } }, "additionalProperties": false }, "attemptId": { "description": "Optional profile-setup funnel correlation UUID.", "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": [ "Management REST APIs" ] } }, "/integrations/onepassword/profile/*": { "get": { "definitions": {}, "description": "Poll an autologin task by id. Returns its state, the current live rationale,\nand (on success) the saved profile id plus a per-domain breakdown. Scoped to\nthe requesting account (or token, for keys not yet mapped to an account) —\nreturns 404 for unknown ids or another account'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": "#/definitions/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": "#/definitions/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": "#/definitions/AutologinDomainStatus" }, "error": { "type": "string" }, "errorCode": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": false, "required": [ "origin", "status" ] }, "AutologinDomainStatus": { "description": "Per-origin progress/outcome as the agent works through the domain list.\nLive: `pending` (not reached), `active` (currently attempting), `tried`\n(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": [ "Management REST APIs" ] } }, "/integrations/script-generator": { "post": { "definitions": {}, "description": "Generates a Browserless automation script (BrowserQL / Playwright JS /\nPlaywright Python) from a natural-language task. A managed agent drives a\nbrowser session; its ordered tool-call transcript is rendered into the\nrequested script(s). Streams Server-Sent Events: status, script, complete,\nerror.", "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": [ "Management REST APIs" ] } }, "/stealth": { "get": { "definitions": {}, "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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for mobile personas (emulationOs=android), e.g. \"pixel-8\",\n\"galaxy-s23\". Omit to auto-pick a device seeded per session (stable per\nidentity, spread across the fleet); an unknown slug does the same.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux | android." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": [ "Browser WebSocket APIs" ] } }, "/chrome/live/*": { "get": { "definitions": {}, "description": "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": [ "Browser WebSocket APIs" ] } }, "/chrome/stealth": { "get": { "definitions": {}, "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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for mobile personas (emulationOs=android), e.g. \"pixel-8\",\n\"galaxy-s23\". Omit to auto-pick a device seeded per session (stable per\nidentity, spread across the fleet); an unknown slug does the same.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux | android." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": [ "Browser WebSocket APIs" ] } }, "/chromium/cli": { "get": { "definitions": {}, "description": "Interactive hosted-agent chat. Browserless runs the LLM server-side (no\ncustomer key) and drives a browser to complete the task. Send newline-JSON\ncontrol frames ({\"type\":\"start\",\"prompt\":\"...\"}) and receive a stream of\ndata / tool_call / tool_result / usage / awaiting_input / end events.", "parameters": [ { "in": "query", "name": "token", "schema": { "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" ] } }, "/live/*": { "get": { "definitions": {}, "description": "Websocket back-end that powers the live session experience.\n\n**Note:** This endpoint is also available at: `/chromium/live/*` for backwards compatibility.", "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": [ "Browser WebSocket APIs" ] } }, "/chromium/stealth": { "get": { "definitions": {}, "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.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for mobile personas (emulationOs=android), e.g. \"pixel-8\",\n\"galaxy-s23\". Omit to auto-pick a device seeded per session (stable per\nidentity, spread across the fleet); an unknown slug does the same.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux | android." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen set, routes requests through this proxy instead of built-in residential proxies.", "type": "string" } }, { "in": "query", "name": "integrationId", "schema": { "description": "Optional 1Password integration id (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "in": "query", "name": "solveCaptchas", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "description": "Override the system-level timeout for this request.\nAccepts 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": [ "Browser WebSocket APIs" ] } }, "/reconnect/*": { "get": { "definitions": {}, "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 nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "integrations", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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": "/reconnect/*", "tags": [ "Browser WebSocket APIs" ] } }, "/session/connect/*": { "get": { "definitions": {}, "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.\n\nThe 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": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "timeout", "schema": { "type": "number" } }, { "in": "query", "name": "token", "schema": { "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": [ "Browser WebSocket APIs" ] } }, "/chromium/stealth/reconnect/*": { "get": { "definitions": {}, "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 nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "integrations", "schema": { "type": "string" } }, { "in": "query", "name": "launch", "schema": { "description": "Launch options, which can be either an object\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "$ref": "#/definitions/BrowserServerOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore 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.\nAccepts 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/reconnect/*", "tags": [ "Browser WebSocket APIs" ] } }, "/chromium/agent": { "get": { "definitions": {}, "description": "WebSocket endpoint for agentic browser interaction. Connect to establish a\npersistent browser session, then send JSON-RPC messages to control the browser.\n\nUses a simple JSON protocol instead of GraphQL:\nSend: { \"id\": 1, \"method\": \"goto\", \"params\": { \"url\": \"https://example.com\" } }\nReceive: { \"id\": 1, \"result\": { \"status\": 200, \"url\": \"https://example.com\" } }\n\nAll BQL mutations are available as methods (goto, click, type, screenshot, etc.).\nAdditionally supports a \"snapshot\" method that returns interactive page elements\nwith CSS selectors, plus tab-management methods (getTabs, switchTab, createTab,\ncloseTab) for multi-tab workflows.", "parameters": [ { "in": "query", "name": "allowedDomains", "schema": { "description": "Optional per-connection narrowing of the integration's allowed-domain list.\nExtracted from the JSON `allowedDomains` query parameter. Can only narrow the\nintegration's domains, never widen them.", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "blockAds", "schema": { "description": "Whether or nor to load ad-blocking extensions for the session.\nThis currently uses uBlock-Lite and may cause certain sites\nto not load properly.", "type": "boolean" } }, { "in": "query", "name": "blockAdsInclude", "schema": { "description": "Ruleset IDs to load when `blockAds` is enabled, as CSV or JSON-array text.", "type": "string" } }, { "in": "query", "name": "blockConsentModals", "schema": { "type": "boolean" } }, { "in": "query", "name": "credentials", "schema": { "$ref": "#/definitions/Record%3Cstring%2Cstring%3E", "description": "Optional alias → `op://…` reference map for the integration above. Extracted\nfrom the JSON `credentials` query parameter. References are not secret;\nresolved values are never stored here. Optional — a connection can also pass\nraw `op://…` references straight to Browserless.loadSecret." } }, { "in": "query", "name": "deviceScaleFactor", "schema": { "description": "Device pixel ratio for the desktop screen above (allowed: 1 or 1.25).\nOmit to default to the seeded/profile scale. Ignored for emulationOs=android.", "type": "number" } }, { "in": "query", "name": "deviceSlot", "schema": { "description": "Pin this session to one of your identity's N stable device slots (0-based,\ndefault N=8). Each slot is one virtual machine: its GPU, screen, cores, memory\nand OS version stay fixed across sessions, so traffic spreads over N machines\ninstead of clustering on one. Requires a desktop emulationOs.", "type": "number" } }, { "in": "query", "name": "emulatedDevice", "schema": { "description": "Device model for mobile personas (emulationOs=android), e.g. \"pixel-8\",\n\"galaxy-s23\". Omit to auto-pick a device seeded per session (stable per\nidentity, spread across the fleet); an unknown slug does the same.", "type": "string" } }, { "in": "query", "name": "emulationOs", "schema": { "$ref": "#/definitions/Platform", "description": "Spoof OS for full per-platform stealth: windows | macos | linux | android." } }, { "in": "query", "name": "externalProxyServer", "schema": { "description": "External proxy server URL for user-provided proxies.\nFormat: http(s)://[username:password@]host:port\nWhen 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 (op_int_…) or label for credential filling on a non-persistent\nconnection. Extracted from the `integrationId` query parameter; the persistent\nsession 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\nof puppeteer.launch options or playwright.launchServer\noptions, depending on the API. Must be either JSON\nobject, or a base64-encoded JSON object.", "anyOf": [ { "$ref": "#/definitions/CDPLaunchOptions" }, { "type": "string" } ] } }, { "in": "query", "name": "profile", "schema": { "description": "Name of an authenticated profile to hydrate into the browser at launch.\nThe profile's cookies, localStorage and IndexedDB are injected via CDP\nbefore your code runs. No-op in builds without a profile subsystem.", "type": "string" } }, { "in": "query", "name": "proxy", "schema": { "$ref": "#/definitions/ProxyType", "description": "The type of proxy to use: 'residential' or 'datacenter'." } }, { "in": "query", "name": "proxyCity", "schema": { "description": "The city to use for the proxy.\n\nAvailable cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN\nDocumentation: 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.\n\nSupported codes: US, GB, FR, DE, etc.\nFull 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.\nRecommended when using proxyCountry to ensure websites render content,\ncurrency, 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.\nMaps to specific proxy vendors internally for optimal access to certain websites.\nOnly applies to the residential network; the datacenter pool ignores it.\nFormat: \"px_\" (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. Off by default.", "enum": [ "0", "1", "false", "true" ], "type": "string" } }, { "in": "query", "name": "record", "schema": { "type": "boolean" } }, { "in": "query", "name": "replay", "schema": { "type": "boolean" } }, { "in": "query", "name": "screen", "schema": { "description": "Desktop screen resolution as WIDTHxHEIGHT (e.g. '1920x1080'). Sets the\nreported screen.*, window size and (with deviceScaleFactor) DPR for a\ndesktop persona. Omit to auto-pick a screen seeded per session (stable per\nidentity, spread across the fleet). Ignored for emulationOs=android.", "type": "string" } }, { "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.\nAccepts 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" ] } } }, "servers": [] }