openapi: 3.0.0
info:
title: Browserbase API
description: Browserbase API for 3rd party developers
version: v1
servers:
- url: "https://api.browserbase.com"
description: Public endpoint
variables: {}
paths:
/v1/contexts:
post:
operationId: Contexts_create
summary: Create a Context
requestBody:
content:
application/json:
schema:
type: object
properties:
projectId:
description: "The Project ID. Can be found in [Settings](https://www.browserbase.com/settings). Optional - if not provided, the project will be inferred from the API key."
type: string
responses:
"201":
description: The request has succeeded and a new resource has been created as a result.
content:
application/json:
schema:
type: object
properties:
id:
type: string
uploadUrl:
description: An upload URL to upload a custom user-data-directory.
type: string
minLength: 1
publicKey:
description: The public key to encrypt the user-data-directory.
type: string
cipherAlgorithm:
description: The cipher algorithm used to encrypt the user-data-directory. AES-256-CBC is currently the only supported algorithm.
type: string
initializationVectorSize:
description: "The initialization vector size used to encrypt the user-data-directory. [Read more about how to use it](/features/contexts)."
type: integer
format: uint8
required:
- id
- uploadUrl
- publicKey
- cipherAlgorithm
- initializationVectorSize
"/v1/contexts/{id}":
get:
operationId: Contexts_get
summary: Get a Context
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/Context"
put:
operationId: Contexts_update
summary: Update a Context
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: object
properties:
id:
type: string
uploadUrl:
description: An upload URL to upload a custom user-data-directory.
type: string
minLength: 1
publicKey:
description: The public key to encrypt the user-data-directory.
type: string
cipherAlgorithm:
description: The cipher algorithm used to encrypt the user-data-directory. AES-256-CBC is currently the only supported algorithm.
type: string
initializationVectorSize:
description: "The initialization vector size used to encrypt the user-data-directory. [Read more about how to use it](/features/contexts)."
type: integer
format: uint8
required:
- id
- uploadUrl
- publicKey
- cipherAlgorithm
- initializationVectorSize
delete:
operationId: Contexts_delete
summary: Delete a Context
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"204":
description: "There is no content to send for this request, but the headers may be useful."
/v1/extensions:
post:
operationId: Extensions_upload
summary: Upload an Extension
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
required:
- file
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/Extension"
"/v1/extensions/{id}":
get:
operationId: Extensions_get
summary: Get an Extension
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/Extension"
delete:
operationId: Extensions_delete
summary: Delete an Extension
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"204":
description: "There is no content to send for this request, but the headers may be useful."
/v1/fetch:
post:
operationId: Fetch_create
summary: Fetch a Page
description: "Fetch a page and return its content, headers, and metadata."
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
url:
description: The URL to fetch
type: string
format: uri
allowRedirects:
description: Whether to follow HTTP redirects
type: boolean
default: false
allowInsecureSsl:
description: Whether to bypass TLS certificate verification
type: boolean
default: false
proxies:
description: Whether to enable proxy support for the request
type: boolean
default: false
required:
- url
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: object
properties:
id:
description: Unique identifier for the fetch request
type: string
statusCode:
description: HTTP status code of the fetched response
type: integer
headers:
description: Response headers as key-value pairs
type: object
additionalProperties:
type: string
content:
description: The response body content
type: string
contentType:
description: The MIME type of the response
type: string
encoding:
description: The character encoding of the response
type: string
required:
- id
- statusCode
- headers
- content
- contentType
- encoding
"400":
description: Invalid request body.
content:
application/json:
schema:
type: object
properties:
statusCode:
description: HTTP status code
type: integer
error:
description: HTTP error name
type: string
message:
description: Human-readable error message
type: string
id:
description: Unique identifier for the fetch request
type: string
required:
- statusCode
- error
- message
"429":
description: Concurrent fetch request limit exceeded.
content:
application/json:
schema:
type: object
properties:
statusCode:
description: HTTP status code
type: integer
error:
description: HTTP error name
type: string
message:
description: Human-readable error message
type: string
id:
description: Unique identifier for the fetch request
type: string
required:
- statusCode
- error
- message
"502":
description: The fetched response was too large or TLS certificate verification failed.
content:
application/json:
schema:
type: object
properties:
statusCode:
description: HTTP status code
type: integer
error:
description: HTTP error name
type: string
message:
description: Human-readable error message
type: string
id:
description: Unique identifier for the fetch request
type: string
required:
- statusCode
- error
- message
- id
"504":
description: The fetch request timed out.
content:
application/json:
schema:
type: object
properties:
statusCode:
description: HTTP status code
type: integer
error:
description: HTTP error name
type: string
message:
description: Human-readable error message
type: string
id:
description: Unique identifier for the fetch request
type: string
required:
- statusCode
- error
- message
- id
/v1/projects:
get:
operationId: Projects_list
summary: List Projects
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Project"
"/v1/projects/{id}":
get:
operationId: Projects_get
summary: Get a Project
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/Project"
"/v1/projects/{id}/usage":
get:
operationId: Projects_usage
summary: Get Project Usage
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/ProjectUsage"
/v1/search:
post:
operationId: Search_web
summary: Web Search
description: Perform a web search and return structured results.
requestBody:
description: Request body for web search
required: true
content:
application/json:
schema:
description: Request body for web search
type: object
properties:
query:
description: The search query string
type: string
maxLength: 200
minLength: 1
numResults:
description: Number of results to return (1-25)
type: integer
default: 10
maximum: 25
minimum: 1
required:
- query
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
description: Response body for web search
type: object
properties:
requestId:
description: Unique identifier for the request
type: string
query:
description: The search query that was executed
type: string
results:
description: List of search results
type: array
items:
type: object
properties:
id:
description: Unique identifier for the result
type: string
url:
description: The URL of the search result
type: string
title:
description: The title of the search result
type: string
author:
description: Author of the content if available
type: string
publishedDate:
description: Publication date in ISO 8601 format
type: string
format: date-time
image:
description: Image URL if available
type: string
favicon:
description: Favicon URL
type: string
required:
- id
- url
- title
required:
- requestId
- query
- results
/v1/sessions:
get:
operationId: Sessions_list
summary: List Sessions
parameters:
- name: status
in: query
required: false
schema:
type: string
enum:
- RUNNING
- ERROR
- TIMED_OUT
- COMPLETED
- name: q
in: query
description: "Query sessions by user metadata. See [Querying Sessions by User Metadata](/features/sessions#querying-sessions-by-user-metadata) for the schema of this query."
required: false
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Session"
post:
operationId: Sessions_create
summary: Create a Session
requestBody:
content:
application/json:
schema:
type: object
properties:
projectId:
description: "The Project ID. Can be found in [Settings](https://www.browserbase.com/settings). Optional - if not provided, the project will be inferred from the API key."
type: string
extensionId:
description: "The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension)."
type: string
browserSettings:
type: object
properties:
context:
type: object
properties:
id:
description: The Context ID.
type: string
persist:
description: Whether or not to persist the context after browsing. Defaults to `false`.
type: boolean
required:
- id
extensionId:
description: "The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension)."
type: string
viewport:
type: object
properties:
width:
description: The width of the browser.
type: integer
height:
description: The height of the browser.
type: integer
blockAds:
description: Enable or disable ad blocking in the browser. Defaults to `false`.
type: boolean
solveCaptchas:
description: Enable or disable captcha solving in the browser. Defaults to `true`.
type: boolean
recordSession:
description: Enable or disable session recording. Defaults to `true`.
type: boolean
logSession:
description: Enable or disable session logging. Defaults to `true`.
type: boolean
advancedStealth:
description: Advanced Browser Stealth Mode
type: boolean
captchaImageSelector:
description: "Custom selector for captcha image. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)"
type: string
captchaInputSelector:
description: "Custom selector for captcha input. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)"
type: string
os:
description: "Operating system for stealth mode. Valid values: windows, mac, linux, mobile, tablet"
type: string
enum:
- windows
- mac
- linux
- mobile
- tablet
timeout:
description: Duration in seconds after which the session will automatically end. Defaults to the Project's `defaultTimeout`.
type: integer
maximum: 21600
minimum: 60
keepAlive:
description: Set to true to keep the session alive even after disconnections. Available on the Hobby Plan and above.
type: boolean
proxies:
description: "Proxy configuration. Can be true for default proxy, or an array of proxy configurations."
anyOf:
- type: array
items:
anyOf:
- $ref: "#/components/schemas/BrowserbaseProxyConfig"
- $ref: "#/components/schemas/ExternalProxyConfig"
- $ref: "#/components/schemas/NoneProxyConfig"
- type: boolean
region:
description: The region where the Session should run.
type: string
default: us-west-2
enum:
- us-west-2
- us-east-1
- eu-central-1
- ap-southeast-1
userMetadata:
description: "Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata)."
type: object
additionalProperties: true
properties: {}
responses:
"201":
description: The request has succeeded and a new resource has been created as a result.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/Session"
- type: object
properties:
connectUrl:
description: WebSocket URL to connect to the Session.
type: string
format: uri
seleniumRemoteUrl:
description: HTTP URL to connect to the Session.
type: string
format: uri
signingKey:
description: Signing key to use when connecting to the Session via HTTP.
type: string
required:
- connectUrl
- seleniumRemoteUrl
- signingKey
x-codeSamples:
- lang: cURL
source: |-
curl --request POST \
--url https://api.browserbase.com/v1/sessions \
--header 'Content-Type: application/json' \
--header 'X-BB-API-Key: <api-key>' \
--data '{}'
- lang: JavaScript
source: |-
fetch('https://api.browserbase.com/v1/sessions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-BB-API-Key': '<api-key>'
},
body: JSON.stringify({})
})
- lang: Python
source: |-
import requests
url = "https://api.browserbase.com/v1/sessions"
payload = {}
headers = {
"X-BB-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.request("POST", url, json=payload, headers=headers)
print(response.text)
- lang: PHP
source: |-
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.browserbase.com/v1/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{}",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-BB-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
- lang: Go
source: "package main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.browserbase.com/v1/sessions\"\n\n\tpayload := strings.NewReader(\"{}\")\n\n\treq, _ := http.NewRequest(\"POST\", url, payload)\n\n\treq.Header.Add(\"X-BB-API-Key\", \"<api-key>\")\n\treq.Header.Add(\"Content-Type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
- lang: Java
source: |-
HttpResponse<String> response = Unirest.post("https://api.browserbase.com/v1/sessions")
.header("X-BB-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{}")
.asString();
"/v1/sessions/{id}":
get:
operationId: Sessions_get
summary: Get a Session
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/Session"
- type: object
properties:
connectUrl:
description: WebSocket URL to connect to the Session.
type: string
format: uri
seleniumRemoteUrl:
description: HTTP URL to connect to the Session.
type: string
format: uri
signingKey:
description: Signing key to use when connecting to the Session via HTTP.
type: string
post:
operationId: Sessions_update
summary: Update a Session
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
projectId:
description: "The Project ID. Can be found in [Settings](https://www.browserbase.com/settings). Optional - if not provided, the project will be inferred from the API key."
type: string
status:
description: Set to `REQUEST_RELEASE` to request that the session complete. Use before session's timeout to avoid additional charges.
type: string
enum:
- REQUEST_RELEASE
required:
- status
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/Session"
"/v1/sessions/{id}/debug":
get:
operationId: Sessions_getDebug
summary: Session Live URLs
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionLiveUrls"
"/v1/sessions/{id}/downloads":
get:
operationId: Sessions_getDownloads
summary: Session Downloads
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/zip:
schema:
type: string
format: binary
delete:
operationId: Sessions_deleteDownloads
summary: Delete Session Downloads
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"204":
description: "There is no content to send for this request, but the headers may be useful."
"/v1/sessions/{id}/logs":
get:
operationId: Sessions_getLogs
summary: Session Logs
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SessionLog"
"/v1/sessions/{id}/recording":
get:
operationId: Sessions_getRecording
summary: Session Recording
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SessionRecording"
"/v1/sessions/{id}/uploads":
post:
operationId: Sessions_uploadFile
summary: Create Session Uploads
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
required:
- file
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
components:
schemas:
BrowserbaseProxyConfig:
type: object
properties:
type:
description: Type of proxy. Always use 'browserbase' for the Browserbase managed proxy network.
type: string
enum:
- browserbase
geolocation:
description: Geographic location for the proxy. Optional.
type: object
properties:
city:
description: Name of the city. Use spaces for multi-word city names. Optional.
type: string
state:
description: US state code (2 characters). Must also specify US as the country. Optional.
type: string
maxLength: 2
minLength: 2
country:
description: Country code in ISO 3166-1 alpha-2 format
type: string
maxLength: 2
minLength: 2
required:
- country
domainPattern:
description: "Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional."
type: string
required:
- type
Context:
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
projectId:
description: The Project ID linked to the uploaded Context.
type: string
required:
- id
- createdAt
- updatedAt
- projectId
Extension:
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
fileName:
type: string
minLength: 1
projectId:
description: The Project ID linked to the uploaded Extension.
type: string
required:
- id
- createdAt
- updatedAt
- fileName
- projectId
ExternalProxyConfig:
type: object
properties:
type:
description: Type of proxy. Always 'external' for this config.
type: string
enum:
- external
server:
description: Server URL for external proxy. Required.
type: string
domainPattern:
description: "Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional."
type: string
username:
description: Username for external proxy authentication. Optional.
type: string
password:
description: Password for external proxy authentication. Optional.
type: string
required:
- type
- server
NoneProxyConfig:
type: object
properties:
type:
description: Type of proxy. Always 'none' for this config.
type: string
enum:
- none
domainPattern:
description: "Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional."
type: string
required:
- type
Project:
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
name:
type: string
minLength: 1
ownerId:
type: string
defaultTimeout:
type: integer
maximum: 21600
minimum: 60
concurrency:
description: The maximum number of sessions that this project can run concurrently.
type: integer
minimum: 1
required:
- id
- createdAt
- updatedAt
- name
- ownerId
- defaultTimeout
- concurrency
ProjectUsage:
type: object
properties:
browserMinutes:
type: integer
minimum: 0
proxyBytes:
type: integer
minimum: 0
required:
- browserMinutes
- proxyBytes
Session:
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
projectId:
description: The Project ID linked to the Session.
type: string
startedAt:
type: string
format: date-time
endedAt:
type: string
format: date-time
expiresAt:
type: string
format: date-time
status:
type: string
enum:
- RUNNING
- ERROR
- TIMED_OUT
- COMPLETED
proxyBytes:
description: "Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips)"
type: integer
keepAlive:
description: Indicates if the Session was created to be kept alive upon disconnections
type: boolean
contextId:
description: Optional. The Context linked to the Session.
type: string
region:
description: The region where the Session is running.
type: string
enum:
- us-west-2
- us-east-1
- eu-central-1
- ap-southeast-1
userMetadata:
description: "Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata)."
type: object
additionalProperties: true
properties: {}
required:
- id
- createdAt
- updatedAt
- projectId
- startedAt
- expiresAt
- status
- proxyBytes
- keepAlive
- region
SessionLiveUrls:
type: object
properties:
debuggerFullscreenUrl:
type: string
format: uri
debuggerUrl:
type: string
format: uri
pages:
type: array
items:
type: object
properties:
id:
type: string
url:
type: string
format: uri
faviconUrl:
type: string
format: uri
title:
type: string
debuggerUrl:
type: string
format: uri
debuggerFullscreenUrl:
type: string
format: uri
required:
- id
- url
- faviconUrl
- title
- debuggerUrl
- debuggerFullscreenUrl
wsUrl:
type: string
format: uri
required:
- debuggerFullscreenUrl
- debuggerUrl
- pages
- wsUrl
SessionLog:
type: object
properties:
method:
type: string
pageId:
type: integer
sessionId:
type: string
request:
type: object
properties:
timestamp:
description: milliseconds that have elapsed since the UNIX epoch
type: integer
params:
type: object
additionalProperties: true
properties: {}
rawBody:
type: string
required:
- params
- rawBody
response:
type: object
properties:
timestamp:
description: milliseconds that have elapsed since the UNIX epoch
type: integer
result:
type: object
additionalProperties: true
properties: {}
rawBody:
type: string
required:
- result
- rawBody
timestamp:
description: milliseconds that have elapsed since the UNIX epoch
type: integer
frameId:
type: string
loaderId:
type: string
required:
- method
- pageId
- sessionId
SessionRecording:
type: object
properties:
data:
description: "See [rrweb documentation](https://github.com/rrweb-io/rrweb/blob/master/docs/recipes/dive-into-event.md)."
type: object
additionalProperties: true
properties: {}
sessionId:
type: string
timestamp:
description: milliseconds that have elapsed since the UNIX epoch
type: integer
type:
type: integer
required:
- data
- sessionId
- timestamp
- type
securitySchemes:
BrowserbaseAuth:
type: apiKey
in: header
name: X-BB-API-Key
description: "Your [Browserbase API Key](https://www.browserbase.com/settings)."
tags: []
security:
- BrowserbaseAuth: []