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 }