openapi: 3.0.0
info:
  title: Browserbase API
  description: Browserbase API for 3rd party developers
  version: v1
tags: []
paths:
  /v1/contexts:
    post:
      operationId: Contexts_create
      summary: Create a Context
      parameters: []
      responses:
        "201":
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateContextResponse"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateContext"
  /v1/contexts/{id}:
    get:
      operationId: Contexts_get
      summary: Context
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/uuid"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Context"
    put:
      operationId: Contexts_update
      summary: Update 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/CreateContextResponse"
  /v1/extensions:
    post:
      operationId: Extensions_upload
      summary: Upload an Extension
      parameters: []
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Extension"
        "415":
          description: Client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
              required:
                - file
  /v1/extensions/{id}:
    get:
      operationId: Extensions_get
      summary: Extension
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/uuid"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Extension"
    delete:
      operationId: Extensions_delete
      summary: Delete Extension
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/uuid"
      responses:
        "204":
          description: "There is no content to send for this request, but the headers may be useful. "
  /v1/projects:
    get:
      operationId: Projects_list
      summary: List all projects
      parameters: []
      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: Project
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/uuid"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
  /v1/projects/{id}/usage:
    get:
      operationId: Projects_usage
      summary: Project Usage
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/uuid"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectUsage"
  /v1/sessions:
    get:
      operationId: Sessions_list
      summary: List Sessions
      parameters:
        - name: status
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/SessionStatus"
          explode: false
      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
      parameters: []
      responses:
        "201":
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  projectId:
                    allOf:
                      - $ref: "#/components/schemas/uuid"
                    description: The Project ID linked to the Session.
                  startedAt:
                    type: string
                    format: date-time
                  endedAt:
                    type: string
                    format: date-time
                  expiresAt:
                    type: string
                    format: date-time
                  status:
                    $ref: "#/components/schemas/SessionStatus"
                  proxyBytes:
                    type: integer
                    description: Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips)
                  avgCpuUsage:
                    type: integer
                    description: CPU used by the Session
                  memoryUsage:
                    type: integer
                    description: Memory used by the Session
                  keepAlive:
                    type: boolean
                    description: Indicates if the Session was created to be kept alive upon disconnections
                  contextId:
                    allOf:
                      - $ref: "#/components/schemas/uuid"
                    description: Optional. The Context linked to the Session.
                  region:
                    allOf:
                      - $ref: "#/components/schemas/Region"
                    description: The region where the Session is running.
                  id:
                    $ref: "#/components/schemas/uuid"
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
                  connectUrl:
                    type: string
                    format: uri
                    description: WebSocket URL to connect to the Session.
                  seleniumRemoteUrl:
                    type: string
                    format: uri
                    description: HTTP URL to connect to the Session.
                  signingKey:
                    type: string
                    description: Signing key to use when connecting to the Session via HTTP.
                required:
                  - projectId
                  - startedAt
                  - expiresAt
                  - status
                  - proxyBytes
                  - keepAlive
                  - region
                  - id
                  - createdAt
                  - updatedAt
                  - connectUrl
                  - seleniumRemoteUrl
                  - signingKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSession"
      x-codeSamples:
        - lang: cURL
          source: |-
            curl --request POST \
              --url https://www.browserbase.com/v1/sessions \
              --header 'Content-Type: application/json' \
              --header 'X-BB-API-Key: <api-key>' \
              --data '{"projectId": "<project-id>"}'
        - lang: JavaScript
          source: |-
            fetch('https://www.browserbase.com/v1/sessions', {
              method: 'POST',
              headers: {
                'Content-Type': 'application/json',
                'X-BB-API-Key': '<api-key>'
              },
              body: JSON.stringify({
                "projectId": "<project-id>",
              })
            })
        - lang: Python
          source: |-
            import requests

            url = "https://www.browserbase.com/v1/sessions"

            payload = {
                "projectId": "<project-id>",
            }
            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://www.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 => "{"projectId": "<project-id>"}",
              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

            import (
            	"fmt"
            	"strings"
            	"net/http"
            	"io/ioutil"
            )

            func main() {

            	url := "https://www.browserbase.com/v1/sessions"

            	payload := strings.NewReader("{"projectId": "<project-id>"}")

            	req, _ := http.NewRequest("POST", url, payload)

            	req.Header.Add("X-BB-API-Key", "<api-key>")
            	req.Header.Add("Content-Type", "application/json")

            	res, _ := http.DefaultClient.Do(req)

            	defer res.Body.Close()
            	body, _ := ioutil.ReadAll(res.Body)

            	fmt.Println(res)
            	fmt.Println(string(body))

            }
        - lang: Java
          source: |-
            HttpResponse<String> response = Unirest.post("https://www.browserbase.com/v1/sessions")
              .header("X-BB-API-Key", "<api-key>")
              .header("Content-Type", "application/json")
              .body("{"projectId": "<project-id>"}")
              .asString();
  /v1/sessions/{id}:
    get:
      operationId: Sessions_get
      summary: Session
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/uuid"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Session"
    post:
      operationId: Sessions_update
      summary: Update Session
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Session"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SessionUpdate"
  /v1/sessions/{id}/debug:
    get:
      operationId: Sessions_getDebug
      summary: Session Live URLs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/uuid"
      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:
            $ref: "#/components/schemas/uuid"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /v1/sessions/{id}/logs:
    get:
      operationId: Sessions_getLogs
      summary: Session Logs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/uuid"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SessionLog"
        "422":
          description: Client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/sessions/{id}/recording:
    get:
      operationId: Sessions_getRecording
      summary: Session Recording
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/uuid"
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SessionRecording"
        "422":
          description: Client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/sessions/{id}/uploads:
    post:
      operationId: Sessions_uploadFile
      summary: Create Session Uploads
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
        "415":
          description: Client error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
              required:
                - file
security:
  - BrowserbaseAuth: []
components:
  schemas:
    BrowserbaseAuth:
      type: object
      required:
        - type
        - in
        - name
      properties:
        type:
          type: string
          enum:
            - apiKey
          description: API key authentication
        in:
          type: string
          enum:
            - header
          description: location of the API key
        name:
          type: string
          enum:
            - X-BB-API-Key
          description: name of the API key
      description: Your [Browserbase API Key](https://www.browserbase.com/settings).
    BrowserbaseProxyConfig:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - browserbase
          description: Type of proxy. Always use 'browserbase' for the Browserbase managed proxy network.
        geolocation:
          allOf:
            - $ref: "#/components/schemas/GeolocationConfig"
          description: Geographic location for the proxy. Optional.
        domainPattern:
          type: string
          description: Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional.
    Context:
      type: object
      required:
        - id
        - createdAt
        - updatedAt
        - projectId
      properties:
        id:
          $ref: "#/components/schemas/uuid"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        projectId:
          allOf:
            - $ref: "#/components/schemas/uuid"
          description: The Project ID linked to the uploaded Context.
    ContextSetting:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/uuid"
          description: The Context ID.
        persist:
          type: boolean
          description: Whether or not to persist the context after browsing. Defaults to `false`.
    CreateContext:
      type: object
      required:
        - projectId
      properties:
        projectId:
          allOf:
            - $ref: "#/components/schemas/uuid"
          description: The Project ID. Can be found in [Settings](https://www.browserbase.com/settings).
    CreateContextResponse:
      type: object
      required:
        - id
        - uploadUrl
        - publicKey
        - cipherAlgorithm
        - initializationVectorSize
      properties:
        id:
          $ref: "#/components/schemas/uuid"
        uploadUrl:
          type: string
          minLength: 1
          description: An upload URL to upload a custom user-data-directory.
        publicKey:
          type: string
          description: The public key to encrypt the user-data-directory.
        cipherAlgorithm:
          type: string
          description: The cipher algorithm used to encrypt the user-data-directory. AES-256-CBC is currently the only supported algorithm.
        initializationVectorSize:
          type: integer
          format: uint8
          description: The initialization vector size used to encrypt the user-data-directory. [Read more about how to use it](/features/contexts).
    CreateSession:
      type: object
      required:
        - projectId
      properties:
        projectId:
          allOf:
            - $ref: "#/components/schemas/uuid"
          description: The Project ID. Can be found in [Settings](https://www.browserbase.com/settings).
        extensionId:
          allOf:
            - $ref: "#/components/schemas/uuid"
          description: The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension).
        browserSettings:
          $ref: "#/components/schemas/SessionBrowserSettings"
        timeout:
          type: integer
          minimum: 60
          maximum: 21600
          description: Duration in seconds after which the session will automatically end. Defaults to the Project's `defaultTimeout`.
        keepAlive:
          type: boolean
          description: Set to true to keep the session alive even after disconnections. This is available on the Startup plan only.
        proxies:
          description: Proxy configuration. Can be true for default proxy, or an array of proxy configurations.
        region:
          allOf:
            - $ref: "#/components/schemas/Region"
          description: The region where the Session should run.
    CreateSessionConnectDetails:
      type: object
      required:
        - connectUrl
        - seleniumRemoteUrl
        - signingKey
      properties:
        connectUrl:
          type: string
          format: uri
          description: WebSocket URL to connect to the Session.
        seleniumRemoteUrl:
          type: string
          format: uri
          description: HTTP URL to connect to the Session.
        signingKey:
          type: string
          description: Signing key to use when connecting to the Session via HTTP.
    Entity:
      type: object
      required:
        - id
        - createdAt
        - updatedAt
      properties:
        id:
          $ref: "#/components/schemas/uuid"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
        message:
          type: string
    Extension:
      type: object
      required:
        - id
        - createdAt
        - updatedAt
        - fileName
        - projectId
      properties:
        id:
          $ref: "#/components/schemas/uuid"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        fileName:
          type: string
          minLength: 1
        projectId:
          allOf:
            - $ref: "#/components/schemas/uuid"
          description: The Project ID linked to the uploaded Extension.
    ExternalProxyConfig:
      type: object
      required:
        - type
        - server
      properties:
        type:
          type: string
          enum:
            - external
          description: Type of proxy. Always 'external' for this config.
        server:
          type: string
          description: Server URL for external proxy. Required.
        domainPattern:
          type: string
          description: Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional.
        username:
          type: string
          description: Username for external proxy authentication. Optional.
        password:
          type: string
          description: Password for external proxy authentication. Optional.
    Fingerprint:
      type: object
      properties:
        httpVersion:
          type: number
          enum:
            - 1
            - 2
        browsers:
          type: array
          items:
            type: string
            enum:
              - chrome
              - edge
              - firefox
              - safari
        devices:
          type: array
          items:
            type: string
            enum:
              - desktop
              - mobile
        locales:
          type: array
          items:
            type: string
          description: Full list of locales is available [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language).
        operatingSystems:
          type: array
          items:
            type: string
            enum:
              - android
              - ios
              - linux
              - macos
              - windows
          description: 'Note: `operatingSystems` set to `ios` or `android` requires `devices` to include `"mobile"`.'
        screen:
          $ref: "#/components/schemas/FingerprintScreen"
    FingerprintScreen:
      type: object
      properties:
        maxHeight:
          type: integer
        maxWidth:
          type: integer
        minHeight:
          type: integer
        minWidth:
          type: integer
    GeolocationConfig:
      type: object
      required:
        - country
      properties:
        city:
          type: string
          description: Name of the city. Use spaces for multi-word city names. Optional.
        state:
          type: string
          minLength: 2
          maxLength: 2
          description: US state code (2 characters). Must also specify US as the country. Optional.
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: Country code in ISO 3166-1 alpha-2 format
      description: Configuration for geolocation
    Project:
      type: object
      required:
        - id
        - createdAt
        - updatedAt
        - name
        - ownerId
        - defaultTimeout
      properties:
        id:
          $ref: "#/components/schemas/uuid"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        name:
          type: string
          minLength: 1
        ownerId:
          type: string
        defaultTimeout:
          type: integer
          minimum: 60
          maximum: 21600
    ProjectUsage:
      type: object
      required:
        - browserMinutes
        - proxyBytes
      properties:
        browserMinutes:
          type: integer
          minimum: 0
        proxyBytes:
          type: integer
          minimum: 0
    Region:
      type: string
      enum:
        - us-west-2
        - us-east-1
        - eu-central-1
        - ap-southeast-1
    Session:
      type: object
      required:
        - id
        - createdAt
        - updatedAt
        - projectId
        - startedAt
        - expiresAt
        - status
        - proxyBytes
        - keepAlive
        - region
      properties:
        id:
          $ref: "#/components/schemas/uuid"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        projectId:
          allOf:
            - $ref: "#/components/schemas/uuid"
          description: The Project ID linked to the Session.
        startedAt:
          type: string
          format: date-time
        endedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        status:
          $ref: "#/components/schemas/SessionStatus"
        proxyBytes:
          type: integer
          description: Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips)
        avgCpuUsage:
          type: integer
          description: CPU used by the Session
        memoryUsage:
          type: integer
          description: Memory used by the Session
        keepAlive:
          type: boolean
          description: Indicates if the Session was created to be kept alive upon disconnections
        contextId:
          allOf:
            - $ref: "#/components/schemas/uuid"
          description: Optional. The Context linked to the Session.
        region:
          allOf:
            - $ref: "#/components/schemas/Region"
          description: The region where the Session is running.
    SessionBrowserSettings:
      type: object
      properties:
        context:
          $ref: "#/components/schemas/ContextSetting"
        extensionId:
          allOf:
            - $ref: "#/components/schemas/uuid"
          description: The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension).
        fingerprint:
          allOf:
            - $ref: "#/components/schemas/Fingerprint"
          description: See usage examples [in the Stealth Mode page](/features/stealth-mode#fingerprinting).
        viewport:
          $ref: "#/components/schemas/SessionBrowserSettingsViewport"
        blockAds:
          type: boolean
          description: Enable or disable ad blocking in the browser. Defaults to `false`.
        solveCaptchas:
          type: boolean
          description: Enable or disable captcha solving in the browser. Defaults to `true`.
        recordSession:
          type: boolean
          description: Enable or disable session recording. Defaults to `true`.
        logSession:
          type: boolean
          description: Enable or disable session logging. Defaults to `true`.
    SessionBrowserSettingsViewport:
      type: object
      properties:
        width:
          type: integer
        height:
          type: integer
    SessionLiveUrls:
      type: object
      required:
        - debuggerFullscreenUrl
        - debuggerUrl
        - pages
        - wsUrl
      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
    SessionLog:
      type: object
      required:
        - eventId
        - method
        - pageId
        - sessionId
        - timestamp
      properties:
        eventId:
          type: string
        method:
          type: string
        pageId:
          type: integer
        request:
          $ref: "#/components/schemas/SessionLogRequestBody"
        response:
          $ref: "#/components/schemas/SessionLogResponseBody"
        sessionId:
          type: string
        timestamp:
          type: integer
          description: milliseconds that have elapsed since the UNIX epoch
        frameId:
          type: string
        loaderId:
          type: string
    SessionLogRequestBody:
      type: object
      required:
        - timestamp
        - params
        - rawBody
      properties:
        timestamp:
          type: integer
          description: milliseconds that have elapsed since the UNIX epoch
        params:
          type: object
          additionalProperties: {}
        rawBody:
          type: string
    SessionLogResponseBody:
      type: object
      required:
        - timestamp
        - result
        - rawBody
      properties:
        timestamp:
          type: integer
          description: milliseconds that have elapsed since the UNIX epoch
        result:
          type: object
          additionalProperties: {}
        rawBody:
          type: string
    SessionRecording:
      type: object
      required:
        - id
        - data
        - sessionId
        - timestamp
        - type
      properties:
        id:
          type: string
        data:
          type: object
          additionalProperties: {}
          description: See [rrweb documentation](https://github.com/rrweb-io/rrweb/blob/master/docs/recipes/dive-into-event.md).
        sessionId:
          type: string
        timestamp:
          type: integer
          description: milliseconds that have elapsed since the UNIX epoch
        type:
          type: integer
    SessionStatus:
      type: string
      enum:
        - RUNNING
        - ERROR
        - TIMED_OUT
        - COMPLETED
    SessionUpdate:
      type: object
      required:
        - projectId
        - status
      properties:
        projectId:
          allOf:
            - $ref: "#/components/schemas/uuid"
          description: The Project ID. Can be found in [Settings](https://www.browserbase.com/settings).
        status:
          type: string
          enum:
            - REQUEST_RELEASE
          description: Set to `REQUEST_RELEASE` to request that the session complete. Use before session's timeout to avoid additional charges.
    Versions:
      type: string
      enum:
        - v1
    uuid:
      type: string
  securitySchemes:
    BrowserbaseAuth:
      type: apiKey
      in: header
      name: X-BB-API-Key
      description: Your [Browserbase API Key](https://www.browserbase.com/settings).
servers:
  - url: https://www.browserbase.com
    description: Public endpoint
    variables: {}