BRbrowserbase

Start a new browser session

Changed on

Creates a new browser session with the specified configuration. Returns a session ID used for all subsequent operations.

post/v1/sessions/start

Request

  • Base URL
    https://api.stagehand.browserbase.com
  • Auth
    API key in header x-bb-api-key and API key in header x-bb-project-id

Headers

x-stream-response'true' | 'false'

Whether to stream the response via SSE

Example:true

Request body

modelNamestring required

Model name to use for AI operations

domSettleTimeoutMsnumber

Timeout in ms to wait for DOM to settle

verbose0 | 1 | 2

Logging verbosity level (0=quiet, 1=normal, 2=debug)

systemPromptstring

Custom system prompt for AI operations

selfHealboolean

Enable self-healing for failed actions

browserbaseSessionIDstring

Existing Browserbase session ID to resume

experimentalboolean
waitForCaptchaSolvesboolean

Wait for captcha solves (deprecated, v2 only)

actTimeoutMsnumber

Timeout in ms for act operations (deprecated, v2 only)

Example request

{
  "modelName": "openai/gpt-5.4-mini",
  "domSettleTimeoutMs": 5000,
  "verbose": 1,
  "browser": {
    "type": "local",
    "cdpUrl": "ws://localhost:9222"
  },
  "selfHeal": true
}

Response

Default Response

successboolean required

Indicates whether the request was successful

Example response

{
  "data": {
    "sessionId": "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
    "cdpUrl": "wss://connect.browserbase.com/?signingKey=abc123"
  }
}

Changes

  • 0572d68a1e5eRevision changes
    • breaking

      removed subschema #2: ProxyConfigList from the / request property anyOf list

    • breaking

      added 'propertyNames' constraint to the request property //

    • breaking

      added 'propertyNames' constraint to the request property /

    • info

      added subschema #2 to the / request property anyOf list

  • 09241a1f0ee0Revision changes
    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      request property / deprecated