openapi: 3.1.0
info:
title: Browserbase API
description: >-
Browserbase exposes managed headless Chromium browser sessions, contexts,
projects, recordings, logs, and downloads for AI agents and web automation.
Requests authenticate via the X-BB-API-Key header.
version: v1
contact:
name: Browserbase
url: https://docs.browserbase.com
servers:
- url: https://api.browserbase.com/v1
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Sessions
- name: Contexts
- name: Projects
- name: Extensions
paths:
/sessions:
post:
summary: Create a session
operationId: createSession
tags: [Sessions]
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/SessionCreate" }
responses:
"201":
description: Created
content:
application/json: { schema: { $ref: "#/components/schemas/Session" } }
get:
summary: List sessions
operationId: listSessions
tags: [Sessions]
parameters:
- { name: status, in: query, schema: { type: string, enum: [RUNNING, ERROR, TIMED_OUT, COMPLETED] } }
responses:
"200":
description: List of sessions
content:
application/json:
schema:
type: array
items: { $ref: "#/components/schemas/Session" }
/sessions/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
summary: Get a session
operationId: getSession
tags: [Sessions]
responses:
"200":
description: Session
content:
application/json: { schema: { $ref: "#/components/schemas/Session" } }
post:
summary: Update a session
operationId: updateSession
tags: [Sessions]
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status: { type: string, enum: [REQUEST_RELEASE] }
responses:
"200":
description: Session updated
content:
application/json: { schema: { $ref: "#/components/schemas/Session" } }
/sessions/{id}/logs:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
summary: Get session logs
operationId: getSessionLogs
tags: [Sessions]
responses:
"200":
description: Logs
content:
application/json:
schema:
type: array
items: { type: object }
/sessions/{id}/recording:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
summary: Get session recording
operationId: getSessionRecording
tags: [Sessions]
responses:
"200":
description: Recording events
content:
application/json:
schema:
type: array
items: { type: object }
/sessions/{id}/downloads:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
summary: Get session downloads
operationId: getSessionDownloads
tags: [Sessions]
responses:
"200":
description: Downloads zipped
content:
application/zip:
schema: { type: string, format: binary }
/sessions/{id}/debug:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
summary: Get session debug URLs
operationId: getSessionDebug
tags: [Sessions]
responses:
"200":
description: Debug URLs
content:
application/json:
schema:
type: object
properties:
debuggerUrl: { type: string, format: uri }
debuggerFullscreenUrl: { type: string, format: uri }
wsUrl: { type: string }
/contexts:
post:
summary: Create a context
operationId: createContext
tags: [Contexts]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [projectId]
properties:
projectId: { type: string }
responses:
"200":
description: Context created
content:
application/json: { schema: { $ref: "#/components/schemas/Context" } }
/contexts/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
summary: Get a context
operationId: getContext
tags: [Contexts]
responses:
"200":
description: Context
content:
application/json: { schema: { $ref: "#/components/schemas/Context" } }
put:
summary: Update a context
operationId: updateContext
tags: [Contexts]
responses:
"200":
description: Context updated
content:
application/json: { schema: { $ref: "#/components/schemas/Context" } }
/projects:
get:
summary: List projects
operationId: listProjects
tags: [Projects]
responses:
"200":
description: Projects
content:
application/json:
schema:
type: array
items: { $ref: "#/components/schemas/Project" }
/projects/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
summary: Get a project
operationId: getProject
tags: [Projects]
responses:
"200":
description: Project
content:
application/json: { schema: { $ref: "#/components/schemas/Project" } }
/projects/{id}/usage:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
summary: Get project usage
operationId: getProjectUsage
tags: [Projects]
responses:
"200":
description: Usage
content:
application/json: { schema: { type: object } }
/extensions:
post:
summary: Upload an extension
operationId: uploadExtension
tags: [Extensions]
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file: { type: string, format: binary }
responses:
"200":
description: Extension uploaded
content:
application/json:
schema:
type: object
properties:
id: { type: string }
/extensions/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
summary: Get an extension
operationId: getExtension
tags: [Extensions]
responses:
"200":
description: Extension
content:
application/json: { schema: { type: object } }
delete:
summary: Delete an extension
operationId: deleteExtension
tags: [Extensions]
responses:
"204": { description: Deleted }
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-BB-API-Key
schemas:
SessionCreate:
type: object
required: [projectId]
properties:
projectId: { type: string }
extensionId: { type: string }
browserSettings:
type: object
properties:
context:
type: object
properties:
id: { type: string }
persist: { type: boolean }
viewport:
type: object
properties:
width: { type: integer }
height: { type: integer }
blockAds: { type: boolean }
solveCaptchas: { type: boolean }
recordSession: { type: boolean }
logSession: { type: boolean }
advancedStealth: { type: boolean }
os: { type: string, enum: [windows, mac, linux, mobile, tablet] }
ignoreCertificateErrors: { type: boolean }
timeout: { type: integer, minimum: 60, maximum: 21600 }
keepAlive: { type: boolean }
proxies: { oneOf: [{ type: boolean }, { type: array, items: { type: object } }] }
region: { type: string, enum: [us-west-2, us-east-1, eu-central-1, ap-southeast-1] }
userMetadata: { type: object, additionalProperties: true }
Session:
type: object
properties:
id: { type: string }
connectUrl: { type: string }
seleniumRemoteUrl: { type: string }
signingKey: { type: string }
status: { type: string, enum: [PENDING, RUNNING, ERROR, TIMED_OUT, COMPLETED] }
createdAt: { type: string, format: date-time }
updatedAt: { type: string, format: date-time }
startedAt: { type: string, format: date-time }
expiresAt: { type: string, format: date-time }
projectId: { type: string }
region: { type: string }
keepAlive: { type: boolean }
Context:
type: object
properties:
id: { type: string }
uploadUrl: { type: string, format: uri }
publicKey: { type: string }
cipherAlgorithm: { type: string }
initializationVectorSize: { type: integer }
Project:
type: object
properties:
id: { type: string }
name: { type: string }
ownerId: { type: string }
defaultTimeout: { type: integer }
concurrency: { type: integer }
createdAt: { type: string, format: date-time }
updatedAt: { type: string, format: date-time }