openapi: 3.1.0
info:
  title: Stagehand API
  version: 3.1.0
  description: >-
    Stagehand SDK for AI browser automation [ALPHA]. This API allows clients to

    execute browser automation tasks remotely on the Browserbase cloud.

    All endpoints except /sessions/start require an active session ID.

    Responses are streamed using Server-Sent Events (SSE) when the

    `x-stream-response: true` header is provided.


    This SDK is currently ALPHA software and is not production ready!

    Please try it and give us your feedback, stay tuned for upcoming release
    announcements!
  contact:
    name: Browserbase
    url: https://browserbase.com
components:
  securitySchemes:
    BrowserbaseApiKey:
      type: apiKey
      in: header
      name: x-bb-api-key
      description: Browserbase API key for authentication
    BrowserbaseProjectId:
      type: apiKey
      in: header
      name: x-bb-project-id
      description: >-
        Deprecated. Browserbase API keys are now project-scoped, so this header
        is no longer required.
    ModelApiKey:
      type: apiKey
      in: header
      name: x-model-api-key
      description: API key for the AI model provider (OpenAI, Anthropic, etc.)
  links:
    SessionAct:
      operationId: SessionAct
      parameters:
        id: $response.body#/data/sessionId
      description: Perform an action on the session
    SessionExtract:
      operationId: SessionExtract
      parameters:
        id: $response.body#/data/sessionId
      description: Extract data from the session
    SessionObserve:
      operationId: SessionObserve
      parameters:
        id: $response.body#/data/sessionId
      description: Observe available actions on the session
    SessionNavigate:
      operationId: SessionNavigate
      parameters:
        id: $response.body#/data/sessionId
      description: Navigate to a URL in the session
    SessionAgentExecute:
      operationId: SessionAgentExecute
      parameters:
        id: $response.body#/data/sessionId
      description: Execute an agent on the session
    SessionReplay:
      operationId: SessionReplay
      parameters:
        id: $response.body#/data/sessionId
      description: Replay session metrics
    SessionEnd:
      operationId: SessionEnd
      parameters:
        id: $response.body#/data/sessionId
      description: End the session and release resources
  schemas:
    AgentCacheEntry:
      type: object
      properties:
        cacheKey:
          description: >-
            Opaque cache identifier computed from instruction, URL, options, and
            config
          type: string
        entry:
          description: Serialized cache entry that can be written to disk
      required:
        - cacheKey
        - entry
    BrowserbaseRegion:
      type: string
      enum:
        - us-west-2
        - us-east-1
        - eu-central-1
        - ap-southeast-1
    LocalBrowserLaunchOptions:
      type: object
      properties:
        args:
          type: array
          items:
            type: string
        executablePath:
          type: string
        port:
          type: number
        userDataDir:
          type: string
        preserveUserDataDir:
          type: boolean
        headless:
          type: boolean
        devtools:
          type: boolean
        chromiumSandbox:
          type: boolean
        ignoreDefaultArgs:
          anyOf:
            - type: boolean
            - type: array
              items:
                type: string
        proxy:
          type: object
          properties:
            server:
              type: string
            bypass:
              type: string
            username:
              type: string
            password:
              type: string
          required:
            - server
        locale:
          type: string
        viewport:
          type: object
          properties:
            width:
              type: number
            height:
              type: number
          required:
            - width
            - height
        deviceScaleFactor:
          type: number
        hasTouch:
          type: boolean
        ignoreHTTPSErrors:
          type: boolean
        cdpUrl:
          type: string
        cdpHeaders:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
        connectTimeoutMs:
          type: number
        downloadsPath:
          type: string
        acceptDownloads:
          type: boolean
      additionalProperties: false
    GoogleServiceAccountCredentials:
      type: object
      properties:
        type:
          type: string
          const: service_account
        project_id:
          type: string
        private_key_id:
          type: string
        private_key:
          type: string
        client_email:
          type: string
        client_id:
          type: string
        auth_uri:
          type: string
          format: uri
        token_uri:
          type: string
          format: uri
        auth_provider_x509_cert_url:
          type: string
          format: uri
        client_x509_cert_url:
          type: string
          format: uri
        universe_domain:
          type: string
      required:
        - private_key
        - client_email
      additionalProperties: false
    GoogleServiceAccountAuth:
      type: object
      properties:
        type:
          description: >-
            Use inline Google Cloud service account credentials for provider
            authentication
          type: string
          const: googleServiceAccount
        credentials:
          description: Google Cloud service account credentials
          $ref: '#/components/schemas/GoogleServiceAccountCredentials'
        scopes:
          description: Google auth scopes for the desired API request
          anyOf:
            - type: string
            - type: array
              items:
                type: string
        projectId:
          description: Google Cloud project ID used by google-auth-library
          type: string
        universeDomain:
          description: Google Cloud universe domain
          type: string
      required:
        - type
        - credentials
      additionalProperties: false
    AzureEntraIdAuth:
      type: object
      properties:
        type:
          description: Use a Microsoft Entra ID bearer token for authentication
          type: string
          const: azureEntraId
        token:
          description: Microsoft Entra ID bearer token for Azure OpenAI
          type: string
          minLength: 1
      required:
        - type
        - token
      additionalProperties: false
    VertexProviderOptions:
      type: object
      properties:
        project:
          description: Google Cloud project ID for Vertex AI models
          example: my-gcp-project
          type: string
        location:
          description: Google Cloud location for Vertex AI models
          example: us-central1
          type: string
        baseURL:
          description: Base URL for the Vertex AI provider
          type: string
          format: uri
        headers:
          description: Custom headers sent with every request to the Vertex AI provider
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
      required:
        - project
        - location
      additionalProperties: false
    AzureProviderOptions:
      type: object
      properties:
        resourceName:
          description: Azure OpenAI resource name
          example: my-azure-openai-resource
          type: string
        baseURL:
          description: Base URL for the Azure OpenAI provider
          type: string
          format: uri
        apiVersion:
          description: Azure OpenAI API version
          example: 2024-10-01-preview
          type: string
        useDeploymentBasedUrls:
          description: Whether to use deployment-based Azure OpenAI URLs
          type: boolean
        headers:
          description: Custom headers sent with every request to the Azure OpenAI provider
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
      additionalProperties: false
    VertexModelProviderOptions:
      type: object
      properties:
        vertex:
          description: Vertex AI provider-specific settings
          $ref: '#/components/schemas/VertexProviderOptions'
      required:
        - vertex
      additionalProperties: false
    AzureModelProviderOptions:
      type: object
      properties:
        azure:
          description: Azure OpenAI provider-specific settings
          $ref: '#/components/schemas/AzureProviderOptions'
      required:
        - azure
      additionalProperties: false
    GenericModelConfigObject:
      type: object
      properties:
        modelName:
          description: Model name string with provider prefix (e.g., 'openai/gpt-5-nano')
          example: openai/gpt-5.4-mini
          type: string
        apiKey:
          description: API key for the model provider
          example: sk-some-openai-api-key
          type: string
        baseURL:
          description: Base URL for the model provider
          example: https://api.openai.com/v1
          type: string
          format: uri
        headers:
          description: Custom headers sent with every request to the model provider
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
        openaiEndpointFormat:
          description: >-
            Wire format used by an OpenAI-compatible endpoint. Defaults to the
            Responses API; use chat for Chat Completions-only endpoints.
          example: chat
          type: string
          enum:
            - responses
            - chat
        provider:
          description: AI provider for the model (or provide a baseURL endpoint instead)
          example: openai
          type: string
          enum:
            - openai
            - anthropic
            - google
            - microsoft
            - bedrock
      required:
        - modelName
      additionalProperties: false
    VertexModelConfigObject:
      type: object
      properties:
        modelName:
          description: Model name string with provider prefix (e.g., 'openai/gpt-5-nano')
          example: openai/gpt-5.4-mini
          type: string
        apiKey:
          description: API key for the model provider
          example: sk-some-openai-api-key
          type: string
        baseURL:
          description: Base URL for the model provider
          example: https://api.openai.com/v1
          type: string
          format: uri
        headers:
          description: Custom headers sent with every request to the model provider
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
        provider:
          description: Vertex AI model provider
          type: string
          const: vertex
        auth:
          description: Vertex provider authentication configuration
          $ref: '#/components/schemas/GoogleServiceAccountAuth'
        providerOptions:
          description: Vertex provider-specific model configuration
          $ref: '#/components/schemas/VertexModelProviderOptions'
      required:
        - modelName
        - provider
        - auth
        - providerOptions
      additionalProperties: false
    AzureEntraModelConfigObject:
      type: object
      properties:
        modelName:
          description: Model name string with provider prefix (e.g., 'openai/gpt-5-nano')
          example: openai/gpt-5.4-mini
          type: string
        baseURL:
          description: Base URL for the model provider
          example: https://api.openai.com/v1
          type: string
          format: uri
        headers:
          description: Custom headers sent with every request to the model provider
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
        provider:
          description: Azure OpenAI model provider
          type: string
          const: azure
        providerOptions:
          description: Azure provider-specific model configuration
          $ref: '#/components/schemas/AzureModelProviderOptions'
        auth:
          description: Azure provider authentication configuration
          $ref: '#/components/schemas/AzureEntraIdAuth'
      required:
        - modelName
        - provider
        - providerOptions
        - auth
      additionalProperties: false
    AzureApiKeyModelConfigObject:
      type: object
      properties:
        modelName:
          description: Model name string with provider prefix (e.g., 'openai/gpt-5-nano')
          example: openai/gpt-5.4-mini
          type: string
        apiKey:
          description: API key for the model provider
          example: sk-some-openai-api-key
          type: string
        baseURL:
          description: Base URL for the model provider
          example: https://api.openai.com/v1
          type: string
          format: uri
        headers:
          description: Custom headers sent with every request to the model provider
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
        provider:
          description: Azure OpenAI model provider
          type: string
          const: azure
        providerOptions:
          description: Azure provider-specific model configuration
          $ref: '#/components/schemas/AzureModelProviderOptions'
      required:
        - modelName
        - provider
        - providerOptions
      additionalProperties: false
    AzureModelConfigObject:
      anyOf:
        - $ref: '#/components/schemas/AzureEntraModelConfigObject'
        - $ref: '#/components/schemas/AzureApiKeyModelConfigObject'
    ModelConfigObject:
      anyOf:
        - $ref: '#/components/schemas/VertexModelConfigObject'
        - $ref: '#/components/schemas/AzureModelConfigObject'
        - $ref: '#/components/schemas/GenericModelConfigObject'
    ModelConfig:
      $ref: '#/components/schemas/ModelConfigObject'
    Action:
      description: Action object returned by observe and used by act
      type: object
      properties:
        selector:
          description: CSS selector or XPath for the element
          example: '[data-testid=''submit-button'']'
          type: string
        description:
          description: Human-readable description of the action
          example: Click the submit button
          type: string
        backendNodeId:
          description: Backend node ID for the element
          type: number
        method:
          description: The method to execute (click, fill, etc.)
          example: click
          type: string
        arguments:
          description: Arguments to pass to the method
          example:
            - Hello World
          type: array
          items:
            type: string
      required:
        - selector
        - description
    VariablePrimitive:
      anyOf:
        - type: string
        - type: number
        - type: boolean
    VariableValue:
      anyOf:
        - $ref: '#/components/schemas/VariablePrimitive'
        - type: object
          properties:
            value:
              $ref: '#/components/schemas/VariablePrimitive'
            description:
              type: string
          required:
            - value
          additionalProperties: false
    Variables:
      type: object
      propertyNames:
        type: string
      additionalProperties:
        $ref: '#/components/schemas/VariableValue'
    BrowserConfig:
      type: object
      properties:
        type:
          description: Browser type to use
          example: local
          type: string
          enum:
            - local
            - browserbase
        cdpUrl:
          description: Chrome DevTools Protocol URL for connecting to existing browser
          example: ws://localhost:9222
          type: string
        launchOptions:
          $ref: '#/components/schemas/LocalBrowserLaunchOptions'
    BrowserbaseViewport:
      type: object
      properties:
        width:
          type: number
        height:
          type: number
    BrowserbaseFingerprintScreen:
      type: object
      properties:
        maxHeight:
          type: number
        maxWidth:
          type: number
        minHeight:
          type: number
        minWidth:
          type: number
    BrowserbaseFingerprint:
      type: object
      properties:
        browsers:
          type: array
          items:
            type: string
            enum:
              - chrome
              - edge
              - firefox
              - safari
        devices:
          type: array
          items:
            type: string
            enum:
              - desktop
              - mobile
        httpVersion:
          type: string
          enum:
            - '1'
            - '2'
        locales:
          type: array
          items:
            type: string
        operatingSystems:
          type: array
          items:
            type: string
            enum:
              - android
              - ios
              - linux
              - macos
              - windows
        screen:
          $ref: '#/components/schemas/BrowserbaseFingerprintScreen'
    BrowserbaseContext:
      type: object
      properties:
        id:
          type: string
        persist:
          type: boolean
      required:
        - id
    BrowserbaseBrowserSettings:
      type: object
      properties:
        advancedStealth:
          type: boolean
        blockAds:
          type: boolean
        captchaImageSelector:
          type: string
        captchaInputSelector:
          type: string
        context:
          $ref: '#/components/schemas/BrowserbaseContext'
        extensionId:
          type: string
        fingerprint:
          $ref: '#/components/schemas/BrowserbaseFingerprint'
        logSession:
          type: boolean
        os:
          type: string
          enum:
            - windows
            - mac
            - linux
            - mobile
            - tablet
        recordSession:
          type: boolean
        solveCaptchas:
          type: boolean
        verified:
          type: boolean
        viewport:
          $ref: '#/components/schemas/BrowserbaseViewport'
    BrowserbaseProxyGeolocation:
      type: object
      properties:
        country:
          type: string
        city:
          type: string
        state:
          type: string
      required:
        - country
    BrowserbaseProxyConfig:
      type: object
      properties:
        type:
          type: string
          const: browserbase
        domainPattern:
          type: string
        geolocation:
          $ref: '#/components/schemas/BrowserbaseProxyGeolocation'
      required:
        - type
    ExternalProxyConfig:
      type: object
      properties:
        type:
          type: string
          const: external
        server:
          type: string
        domainPattern:
          type: string
        username:
          type: string
        password:
          type: string
      required:
        - type
        - server
    ProxyConfig:
      oneOf:
        - $ref: '#/components/schemas/BrowserbaseProxyConfig'
        - $ref: '#/components/schemas/ExternalProxyConfig'
      type: object
      discriminator:
        propertyName: type
        mapping:
          browserbase: '#/components/schemas/BrowserbaseProxyConfig'
          external: '#/components/schemas/ExternalProxyConfig'
    BrowserbaseSessionCreateParams:
      type: object
      properties:
        projectId:
          deprecated: true
          description: >-
            Deprecated. Browserbase API keys are now project-scoped, so this
            field is no longer required.
          type: string
        browserSettings:
          $ref: '#/components/schemas/BrowserbaseBrowserSettings'
        extensionId:
          type: string
        keepAlive:
          type: boolean
        proxies:
          anyOf:
            - type: boolean
            - type: array
              items:
                $ref: '#/components/schemas/ProxyConfig'
        region:
          $ref: '#/components/schemas/BrowserbaseRegion'
        timeout:
          type: number
        userMetadata:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
    SessionStartRequest:
      type: object
      properties:
        modelName:
          description: Model name to use for AI operations
          example: openai/gpt-5.4-mini
          type: string
        domSettleTimeoutMs:
          description: Timeout in ms to wait for DOM to settle
          example: 5000
          type: number
        verbose:
          description: Logging verbosity level (0=quiet, 1=normal, 2=debug)
          example: 1
          type: number
          enum:
            - 0
            - 1
            - 2
        systemPrompt:
          description: Custom system prompt for AI operations
          type: string
        browserbaseSessionCreateParams:
          $ref: '#/components/schemas/BrowserbaseSessionCreateParams'
        browser:
          $ref: '#/components/schemas/BrowserConfig'
        selfHeal:
          description: Enable self-healing for failed actions
          example: true
          type: boolean
        browserbaseSessionID:
          description: Existing Browserbase session ID to resume
          type: string
        experimental:
          type: boolean
        waitForCaptchaSolves:
          description: Wait for captcha solves (deprecated, v2 only)
          type: boolean
        actTimeoutMs:
          description: Timeout in ms for act operations (deprecated, v2 only)
          type: number
      required:
        - modelName
    SessionStartResult:
      type: object
      properties:
        sessionId:
          description: Unique Browserbase session identifier
          example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
          type: string
        cdpUrl:
          description: >-
            CDP WebSocket URL for connecting to the Browserbase cloud browser
            (present when available)
          example: wss://connect.browserbase.com/?signingKey=abc123
          anyOf:
            - type: string
            - type: 'null'
        available:
          type: boolean
      required:
        - sessionId
        - available
    ActOptions:
      type: object
      properties:
        model:
          description: >-
            Model configuration object or model name string (e.g.,
            'openai/gpt-5-nano')
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: string
        variables:
          description: >-
            Variables to substitute in the action instruction. Accepts flat
            primitives or { value, description? } objects.
          example:
            username: john_doe
            password:
              value: secret123
              description: The login password
          $ref: '#/components/schemas/Variables'
        timeout:
          description: Timeout in ms for the action
          example: 30000
          type: number
    ActRequest:
      type: object
      properties:
        input:
          description: Natural language instruction or Action object
          example: Click the login button
          anyOf:
            - type: string
            - $ref: '#/components/schemas/Action'
        options:
          $ref: '#/components/schemas/ActOptions'
        frameId:
          description: Target frame ID for the action
          anyOf:
            - type: string
            - type: 'null'
        streamResponse:
          description: Whether to stream the response via SSE
          example: true
          type: boolean
      required:
        - input
    ActResultData:
      type: object
      properties:
        success:
          description: Whether the action completed successfully
          example: true
          type: boolean
        message:
          description: Human-readable result message
          example: Successfully clicked the login button
          type: string
        actionDescription:
          description: Description of the action that was performed
          example: Clicked button with text 'Login'
          type: string
        actions:
          description: List of actions that were executed
          type: array
          items:
            $ref: '#/components/schemas/Action'
      required:
        - success
        - message
        - actionDescription
        - actions
    ActResult:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/ActResultData'
        actionId:
          description: Action ID for tracking
          type: string
      required:
        - result
    ExtractOptions:
      type: object
      properties:
        model:
          description: >-
            Model configuration object or model name string (e.g.,
            'openai/gpt-5-nano')
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: string
        timeout:
          description: Timeout in ms for the extraction
          example: 30000
          type: number
        selector:
          description: CSS selector to scope extraction to a specific element
          example: '#main-content'
          type: string
        ignoreSelectors:
          description: >-
            Selectors for elements and subtrees that should be excluded from
            extraction
          example:
            - nav
            - .cookie-banner
            - '#sidebar-ads'
          type: array
          items:
            type: string
        screenshot:
          description: >-
            When true, include a screenshot of the current viewport in the
            extraction LLM call. Defaults to false.
          example: false
          type: boolean
    ExtractRequest:
      type: object
      properties:
        instruction:
          description: Natural language instruction for what to extract
          example: Extract all product names and prices from the page
          type: string
        schema:
          description: JSON Schema defining the structure of data to extract
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        options:
          $ref: '#/components/schemas/ExtractOptions'
        frameId:
          description: Target frame ID for the extraction
          anyOf:
            - type: string
            - type: 'null'
        streamResponse:
          description: Whether to stream the response via SSE
          example: true
          type: boolean
    ExtractResult:
      type: object
      properties:
        result:
          description: Extracted data matching the requested schema
          x-stainless-any: true
        actionId:
          description: Action ID for tracking
          type: string
      required:
        - result
    ObserveOptions:
      type: object
      properties:
        model:
          description: >-
            Model configuration object or model name string (e.g.,
            'openai/gpt-5-nano')
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: string
        variables:
          description: >-
            Variables whose names are exposed to the model so observe() returns
            %variableName% placeholders in suggested action arguments instead of
            literal values. Accepts flat primitives or { value, description? }
            objects.
          example:
            username:
              value: john@example.com
              description: The login email
            rememberMe: true
          $ref: '#/components/schemas/Variables'
        timeout:
          description: Timeout in ms for the observation
          example: 30000
          type: number
        selector:
          description: CSS selector to scope observation to a specific element
          example: nav
          type: string
        ignoreSelectors:
          description: >-
            Selectors for elements and subtrees that should be excluded from
            observation
          example:
            - nav
            - .cookie-banner
            - '#sidebar-ads'
          type: array
          items:
            type: string
    ObserveRequest:
      type: object
      properties:
        instruction:
          description: Natural language instruction for what actions to find
          example: Find all clickable navigation links
          type: string
        options:
          $ref: '#/components/schemas/ObserveOptions'
        frameId:
          description: Target frame ID for the observation
          anyOf:
            - type: string
            - type: 'null'
        streamResponse:
          description: Whether to stream the response via SSE
          example: true
          type: boolean
    ObserveResult:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/Action'
        actionId:
          description: Action ID for tracking
          type: string
      required:
        - result
    AgentConfig:
      type: object
      properties:
        provider:
          description: >-
            AI provider for the agent (legacy, use model: openai/gpt-5-nano
            instead)
          example: openai
          type: string
          enum:
            - openai
            - anthropic
            - google
            - microsoft
            - bedrock
        model:
          description: >-
            Model configuration object or model name string (e.g.,
            'openai/gpt-5-nano')
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: string
        systemPrompt:
          description: Custom system prompt for the agent
          type: string
        cua:
          description: >-
            Deprecated. Use mode: 'cua' instead. If both are provided, mode
            takes precedence.
          example: true
          type: boolean
        mode:
          description: Tool mode for the agent (dom, hybrid, cua). If set, overrides cua.
          example: cua
          type: string
          enum:
            - dom
            - hybrid
            - cua
        executionModel:
          description: >-
            Model configuration object or model name string (e.g.,
            'openai/gpt-5-nano') for tool execution (observe/act calls within
            agent tools). If not specified, inherits from the main model
            configuration.
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: string
    AgentAction:
      type: object
      properties:
        type:
          description: Type of action taken
          example: click
          type: string
        reasoning:
          description: Agent's reasoning for taking this action
          type: string
        taskCompleted:
          type: boolean
        action:
          type: string
        timeMs:
          description: Time taken for this action in ms
          type: number
        pageText:
          type: string
        pageUrl:
          type: string
        instruction:
          type: string
      required:
        - type
      additionalProperties: {}
    AgentUsage:
      type: object
      properties:
        input_tokens:
          example: 1500
          type: number
        output_tokens:
          example: 250
          type: number
        reasoning_tokens:
          type: number
        cached_input_tokens:
          type: number
        inference_time_ms:
          example: 2500
          type: number
      required:
        - input_tokens
        - output_tokens
        - inference_time_ms
    AgentResultData:
      type: object
      properties:
        success:
          description: Whether the agent completed successfully
          example: true
          type: boolean
        message:
          description: Summary of what the agent accomplished
          example: Successfully logged in and navigated to dashboard
          type: string
        actions:
          type: array
          items:
            $ref: '#/components/schemas/AgentAction'
        completed:
          description: Whether the agent finished its task
          example: true
          type: boolean
        metadata:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        usage:
          $ref: '#/components/schemas/AgentUsage'
      required:
        - success
        - message
        - actions
        - completed
    AgentExecuteOptions:
      type: object
      properties:
        instruction:
          description: Natural language instruction for the agent
          example: >-
            Log in with username 'demo' and password 'test123', then navigate to
            settings
          type: string
        maxSteps:
          description: Maximum number of steps the agent can take
          example: 20
          type: number
        highlightCursor:
          description: Whether to visually highlight the cursor during execution
          example: true
          type: boolean
        useSearch:
          description: >-
            Whether to enable the web search tool powered by Browserbase Search
            API
          example: true
          type: boolean
        toolTimeout:
          description: Timeout in milliseconds for each agent tool call
          example: 30000
          type: number
        variables:
          description: >-
            Variables available to the agent via %variableName% syntax in
            supported tools
          $ref: '#/components/schemas/Variables'
      required:
        - instruction
    AgentExecuteRequest:
      type: object
      properties:
        agentConfig:
          $ref: '#/components/schemas/AgentConfig'
        executeOptions:
          $ref: '#/components/schemas/AgentExecuteOptions'
        frameId:
          description: Target frame ID for the agent
          anyOf:
            - type: string
            - type: 'null'
        streamResponse:
          description: Whether to stream the response via SSE
          example: true
          type: boolean
        shouldCache:
          description: >-
            If true, the server captures a cache entry and returns it to the
            client
          type: boolean
      required:
        - agentConfig
        - executeOptions
    AgentExecuteResult:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/AgentResultData'
        cacheEntry:
          $ref: '#/components/schemas/AgentCacheEntry'
      required:
        - result
    NavigateOptions:
      type: object
      properties:
        referer:
          description: Referer header to send with the request
          type: string
        timeout:
          description: Timeout in ms for the navigation
          example: 30000
          type: number
        waitUntil:
          description: When to consider navigation complete
          example: networkidle
          type: string
          enum:
            - load
            - domcontentloaded
            - networkidle
    NavigateRequest:
      type: object
      properties:
        url:
          description: URL to navigate to
          example: https://example.com
          type: string
        options:
          $ref: '#/components/schemas/NavigateOptions'
        frameId:
          description: Target frame ID for the navigation
          anyOf:
            - type: string
            - type: 'null'
        streamResponse:
          description: Whether to stream the response via SSE
          example: true
          type: boolean
      required:
        - url
    NavigateResult:
      type: object
      properties:
        result:
          description: Navigation response (Playwright Response object or null)
          anyOf:
            - {}
            - type: 'null'
          x-stainless-any: true
        actionId:
          description: Action ID for tracking
          type: string
      required:
        - result
    TokenUsage:
      type: object
      properties:
        inputTokens:
          type: number
        outputTokens:
          type: number
        timeMs:
          type: number
        cost:
          type: number
    ReplayAction:
      type: object
      properties:
        method:
          type: string
        parameters:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        result:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        timestamp:
          type: number
        endTime:
          type: number
        tokenUsage:
          $ref: '#/components/schemas/TokenUsage'
      required:
        - method
        - parameters
        - result
        - timestamp
    ReplayPage:
      type: object
      properties:
        url:
          type: string
        timestamp:
          type: number
        duration:
          type: number
        actions:
          type: array
          items:
            $ref: '#/components/schemas/ReplayAction'
      required:
        - url
        - timestamp
        - duration
        - actions
    ReplayResult:
      type: object
      properties:
        pages:
          type: array
          items:
            $ref: '#/components/schemas/ReplayPage'
        clientLanguage:
          type: string
      required:
        - pages
    StreamEventStatus:
      description: Current status of the streaming operation
      type: string
      enum:
        - starting
        - connected
        - running
        - finished
        - error
    StreamEventType:
      description: Type of stream event - system events or log messages
      type: string
      enum:
        - system
        - log
    StreamEventSystemData:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StreamEventStatus'
        result:
          description: Operation result (present when status is 'finished')
          x-stainless-any: true
        error:
          description: Error message (present when status is 'error')
          type: string
      required:
        - status
    StreamEventLogData:
      type: object
      properties:
        status:
          type: string
          const: running
        message:
          description: Log message from the operation
          type: string
      required:
        - status
        - message
    SessionStartResponse:
      type: object
      properties:
        success:
          description: Indicates whether the request was successful
          type: boolean
        data:
          $ref: '#/components/schemas/SessionStartResultOutput'
      required:
        - success
        - data
      additionalProperties: false
    SessionEndResponse:
      type: object
      properties:
        success:
          description: Indicates whether the request was successful
          type: boolean
      required:
        - success
      additionalProperties: false
    ActResponse:
      type: object
      properties:
        success:
          description: Indicates whether the request was successful
          type: boolean
        data:
          $ref: '#/components/schemas/ActResultOutput'
      required:
        - success
        - data
      additionalProperties: false
    ExtractResponse:
      type: object
      properties:
        success:
          description: Indicates whether the request was successful
          type: boolean
        data:
          $ref: '#/components/schemas/ExtractResultOutput'
      required:
        - success
        - data
      additionalProperties: false
    ObserveResponse:
      type: object
      properties:
        success:
          description: Indicates whether the request was successful
          type: boolean
        data:
          $ref: '#/components/schemas/ObserveResultOutput'
      required:
        - success
        - data
      additionalProperties: false
    AgentExecuteResponse:
      type: object
      properties:
        success:
          description: Indicates whether the request was successful
          type: boolean
        data:
          $ref: '#/components/schemas/AgentExecuteResultOutput'
      required:
        - success
        - data
      additionalProperties: false
    NavigateResponse:
      type: object
      properties:
        success:
          description: Indicates whether the request was successful
          type: boolean
        data:
          $ref: '#/components/schemas/NavigateResultOutput'
      required:
        - success
        - data
      additionalProperties: false
    ReplayResponse:
      type: object
      properties:
        success:
          description: Indicates whether the request was successful
          type: boolean
        data:
          $ref: '#/components/schemas/ReplayResultOutput'
      required:
        - success
        - data
      additionalProperties: false
    AgentCacheEntryOutput:
      type: object
      properties:
        cacheKey:
          description: >-
            Opaque cache identifier computed from instruction, URL, options, and
            config
          type: string
        entry:
          description: Serialized cache entry that can be written to disk
      required:
        - cacheKey
        - entry
      additionalProperties: false
    LocalBrowserLaunchOptionsOutput:
      type: object
      properties:
        args:
          type: array
          items:
            type: string
        executablePath:
          type: string
        port:
          type: number
        userDataDir:
          type: string
        preserveUserDataDir:
          type: boolean
        headless:
          type: boolean
        devtools:
          type: boolean
        chromiumSandbox:
          type: boolean
        ignoreDefaultArgs:
          anyOf:
            - type: boolean
            - type: array
              items:
                type: string
        proxy:
          type: object
          properties:
            server:
              type: string
            bypass:
              type: string
            username:
              type: string
            password:
              type: string
          required:
            - server
          additionalProperties: false
        locale:
          type: string
        viewport:
          type: object
          properties:
            width:
              type: number
            height:
              type: number
          required:
            - width
            - height
          additionalProperties: false
        deviceScaleFactor:
          type: number
        hasTouch:
          type: boolean
        ignoreHTTPSErrors:
          type: boolean
        cdpUrl:
          type: string
        cdpHeaders:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
        connectTimeoutMs:
          type: number
        downloadsPath:
          type: string
        acceptDownloads:
          type: boolean
      additionalProperties: false
    ActionOutput:
      description: Action object returned by observe and used by act
      type: object
      properties:
        selector:
          description: CSS selector or XPath for the element
          example: '[data-testid=''submit-button'']'
          type: string
        description:
          description: Human-readable description of the action
          example: Click the submit button
          type: string
        backendNodeId:
          description: Backend node ID for the element
          type: number
        method:
          description: The method to execute (click, fill, etc.)
          example: click
          type: string
        arguments:
          description: Arguments to pass to the method
          example:
            - Hello World
          type: array
          items:
            type: string
      required:
        - selector
        - description
      additionalProperties: false
    BrowserConfigOutput:
      type: object
      properties:
        type:
          description: Browser type to use
          example: local
          type: string
          enum:
            - local
            - browserbase
        cdpUrl:
          description: Chrome DevTools Protocol URL for connecting to existing browser
          example: ws://localhost:9222
          type: string
        launchOptions:
          $ref: '#/components/schemas/LocalBrowserLaunchOptionsOutput'
      additionalProperties: false
    BrowserbaseViewportOutput:
      type: object
      properties:
        width:
          type: number
        height:
          type: number
      additionalProperties: false
    BrowserbaseFingerprintScreenOutput:
      type: object
      properties:
        maxHeight:
          type: number
        maxWidth:
          type: number
        minHeight:
          type: number
        minWidth:
          type: number
      additionalProperties: false
    BrowserbaseFingerprintOutput:
      type: object
      properties:
        browsers:
          type: array
          items:
            type: string
            enum:
              - chrome
              - edge
              - firefox
              - safari
        devices:
          type: array
          items:
            type: string
            enum:
              - desktop
              - mobile
        httpVersion:
          type: string
          enum:
            - '1'
            - '2'
        locales:
          type: array
          items:
            type: string
        operatingSystems:
          type: array
          items:
            type: string
            enum:
              - android
              - ios
              - linux
              - macos
              - windows
        screen:
          $ref: '#/components/schemas/BrowserbaseFingerprintScreenOutput'
      additionalProperties: false
    BrowserbaseContextOutput:
      type: object
      properties:
        id:
          type: string
        persist:
          type: boolean
      required:
        - id
      additionalProperties: false
    BrowserbaseBrowserSettingsOutput:
      type: object
      properties:
        advancedStealth:
          type: boolean
        blockAds:
          type: boolean
        captchaImageSelector:
          type: string
        captchaInputSelector:
          type: string
        context:
          $ref: '#/components/schemas/BrowserbaseContextOutput'
        extensionId:
          type: string
        fingerprint:
          $ref: '#/components/schemas/BrowserbaseFingerprintOutput'
        logSession:
          type: boolean
        os:
          type: string
          enum:
            - windows
            - mac
            - linux
            - mobile
            - tablet
        recordSession:
          type: boolean
        solveCaptchas:
          type: boolean
        verified:
          type: boolean
        viewport:
          $ref: '#/components/schemas/BrowserbaseViewportOutput'
      additionalProperties: false
    BrowserbaseProxyGeolocationOutput:
      type: object
      properties:
        country:
          type: string
        city:
          type: string
        state:
          type: string
      required:
        - country
      additionalProperties: false
    BrowserbaseProxyConfigOutput:
      type: object
      properties:
        type:
          type: string
          const: browserbase
        domainPattern:
          type: string
        geolocation:
          $ref: '#/components/schemas/BrowserbaseProxyGeolocationOutput'
      required:
        - type
      additionalProperties: false
    ExternalProxyConfigOutput:
      type: object
      properties:
        type:
          type: string
          const: external
        server:
          type: string
        domainPattern:
          type: string
        username:
          type: string
        password:
          type: string
      required:
        - type
        - server
      additionalProperties: false
    ProxyConfigOutput:
      oneOf:
        - $ref: '#/components/schemas/BrowserbaseProxyConfigOutput'
        - $ref: '#/components/schemas/ExternalProxyConfigOutput'
      type: object
      discriminator:
        propertyName: type
        mapping:
          browserbase: '#/components/schemas/BrowserbaseProxyConfigOutput'
          external: '#/components/schemas/ExternalProxyConfigOutput'
    BrowserbaseSessionCreateParamsOutput:
      type: object
      properties:
        projectId:
          deprecated: true
          description: >-
            Deprecated. Browserbase API keys are now project-scoped, so this
            field is no longer required.
          type: string
        browserSettings:
          $ref: '#/components/schemas/BrowserbaseBrowserSettingsOutput'
        extensionId:
          type: string
        keepAlive:
          type: boolean
        proxies:
          anyOf:
            - type: boolean
            - type: array
              items:
                $ref: '#/components/schemas/ProxyConfigOutput'
        region:
          $ref: '#/components/schemas/BrowserbaseRegion'
        timeout:
          type: number
        userMetadata:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
      additionalProperties: false
    SessionStartResultOutput:
      type: object
      properties:
        sessionId:
          description: Unique Browserbase session identifier
          example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
          type: string
        cdpUrl:
          description: >-
            CDP WebSocket URL for connecting to the Browserbase cloud browser
            (present when available)
          example: wss://connect.browserbase.com/?signingKey=abc123
          anyOf:
            - type: string
            - type: 'null'
        available:
          type: boolean
      required:
        - sessionId
        - available
      additionalProperties: false
    ActOptionsOutput:
      type: object
      properties:
        model:
          description: >-
            Model configuration object or model name string (e.g.,
            'openai/gpt-5-nano')
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: string
        variables:
          description: >-
            Variables to substitute in the action instruction. Accepts flat
            primitives or { value, description? } objects.
          example:
            username: john_doe
            password:
              value: secret123
              description: The login password
          $ref: '#/components/schemas/Variables'
        timeout:
          description: Timeout in ms for the action
          example: 30000
          type: number
      additionalProperties: false
    ActResultDataOutput:
      type: object
      properties:
        success:
          description: Whether the action completed successfully
          example: true
          type: boolean
        message:
          description: Human-readable result message
          example: Successfully clicked the login button
          type: string
        actionDescription:
          description: Description of the action that was performed
          example: Clicked button with text 'Login'
          type: string
        actions:
          description: List of actions that were executed
          type: array
          items:
            $ref: '#/components/schemas/ActionOutput'
      required:
        - success
        - message
        - actionDescription
        - actions
      additionalProperties: false
    ActResultOutput:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/ActResultDataOutput'
        actionId:
          description: Action ID for tracking
          type: string
      required:
        - result
      additionalProperties: false
    ExtractOptionsOutput:
      type: object
      properties:
        model:
          description: >-
            Model configuration object or model name string (e.g.,
            'openai/gpt-5-nano')
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: string
        timeout:
          description: Timeout in ms for the extraction
          example: 30000
          type: number
        selector:
          description: CSS selector to scope extraction to a specific element
          example: '#main-content'
          type: string
        ignoreSelectors:
          description: >-
            Selectors for elements and subtrees that should be excluded from
            extraction
          example:
            - nav
            - .cookie-banner
            - '#sidebar-ads'
          type: array
          items:
            type: string
        screenshot:
          description: >-
            When true, include a screenshot of the current viewport in the
            extraction LLM call. Defaults to false.
          example: false
          type: boolean
      additionalProperties: false
    ExtractResultOutput:
      type: object
      properties:
        result:
          description: Extracted data matching the requested schema
          x-stainless-any: true
        actionId:
          description: Action ID for tracking
          type: string
      required:
        - result
      additionalProperties: false
    ObserveOptionsOutput:
      type: object
      properties:
        model:
          description: >-
            Model configuration object or model name string (e.g.,
            'openai/gpt-5-nano')
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: string
        variables:
          description: >-
            Variables whose names are exposed to the model so observe() returns
            %variableName% placeholders in suggested action arguments instead of
            literal values. Accepts flat primitives or { value, description? }
            objects.
          example:
            username:
              value: john@example.com
              description: The login email
            rememberMe: true
          $ref: '#/components/schemas/Variables'
        timeout:
          description: Timeout in ms for the observation
          example: 30000
          type: number
        selector:
          description: CSS selector to scope observation to a specific element
          example: nav
          type: string
        ignoreSelectors:
          description: >-
            Selectors for elements and subtrees that should be excluded from
            observation
          example:
            - nav
            - .cookie-banner
            - '#sidebar-ads'
          type: array
          items:
            type: string
      additionalProperties: false
    ObserveResultOutput:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/ActionOutput'
        actionId:
          description: Action ID for tracking
          type: string
      required:
        - result
      additionalProperties: false
    AgentConfigOutput:
      type: object
      properties:
        provider:
          description: >-
            AI provider for the agent (legacy, use model: openai/gpt-5-nano
            instead)
          example: openai
          type: string
          enum:
            - openai
            - anthropic
            - google
            - microsoft
            - bedrock
        model:
          description: >-
            Model configuration object or model name string (e.g.,
            'openai/gpt-5-nano')
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: string
        systemPrompt:
          description: Custom system prompt for the agent
          type: string
        cua:
          description: >-
            Deprecated. Use mode: 'cua' instead. If both are provided, mode
            takes precedence.
          example: true
          type: boolean
        mode:
          description: Tool mode for the agent (dom, hybrid, cua). If set, overrides cua.
          example: cua
          type: string
          enum:
            - dom
            - hybrid
            - cua
        executionModel:
          description: >-
            Model configuration object or model name string (e.g.,
            'openai/gpt-5-nano') for tool execution (observe/act calls within
            agent tools). If not specified, inherits from the main model
            configuration.
          anyOf:
            - $ref: '#/components/schemas/ModelConfig'
            - type: string
      additionalProperties: false
    AgentUsageOutput:
      type: object
      properties:
        input_tokens:
          example: 1500
          type: number
        output_tokens:
          example: 250
          type: number
        reasoning_tokens:
          type: number
        cached_input_tokens:
          type: number
        inference_time_ms:
          example: 2500
          type: number
      required:
        - input_tokens
        - output_tokens
        - inference_time_ms
      additionalProperties: false
    AgentResultDataOutput:
      type: object
      properties:
        success:
          description: Whether the agent completed successfully
          example: true
          type: boolean
        message:
          description: Summary of what the agent accomplished
          example: Successfully logged in and navigated to dashboard
          type: string
        actions:
          type: array
          items:
            $ref: '#/components/schemas/AgentAction'
        completed:
          description: Whether the agent finished its task
          example: true
          type: boolean
        metadata:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        usage:
          $ref: '#/components/schemas/AgentUsageOutput'
      required:
        - success
        - message
        - actions
        - completed
      additionalProperties: false
    AgentExecuteOptionsOutput:
      type: object
      properties:
        instruction:
          description: Natural language instruction for the agent
          example: >-
            Log in with username 'demo' and password 'test123', then navigate to
            settings
          type: string
        maxSteps:
          description: Maximum number of steps the agent can take
          example: 20
          type: number
        highlightCursor:
          description: Whether to visually highlight the cursor during execution
          example: true
          type: boolean
        useSearch:
          description: >-
            Whether to enable the web search tool powered by Browserbase Search
            API
          example: true
          type: boolean
        toolTimeout:
          description: Timeout in milliseconds for each agent tool call
          example: 30000
          type: number
        variables:
          description: >-
            Variables available to the agent via %variableName% syntax in
            supported tools
          $ref: '#/components/schemas/Variables'
      required:
        - instruction
      additionalProperties: false
    AgentExecuteResultOutput:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/AgentResultDataOutput'
        cacheEntry:
          $ref: '#/components/schemas/AgentCacheEntryOutput'
      required:
        - result
      additionalProperties: false
    NavigateOptionsOutput:
      type: object
      properties:
        referer:
          description: Referer header to send with the request
          type: string
        timeout:
          description: Timeout in ms for the navigation
          example: 30000
          type: number
        waitUntil:
          description: When to consider navigation complete
          example: networkidle
          type: string
          enum:
            - load
            - domcontentloaded
            - networkidle
      additionalProperties: false
    NavigateResultOutput:
      type: object
      properties:
        result:
          description: Navigation response (Playwright Response object or null)
          anyOf:
            - {}
            - type: 'null'
          x-stainless-any: true
        actionId:
          description: Action ID for tracking
          type: string
      required:
        - result
      additionalProperties: false
    TokenUsageOutput:
      type: object
      properties:
        inputTokens:
          type: number
        outputTokens:
          type: number
        timeMs:
          type: number
        cost:
          type: number
      additionalProperties: false
    ReplayActionOutput:
      type: object
      properties:
        method:
          type: string
        parameters:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        result:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        timestamp:
          type: number
        endTime:
          type: number
        tokenUsage:
          $ref: '#/components/schemas/TokenUsageOutput'
      required:
        - method
        - parameters
        - result
        - timestamp
      additionalProperties: false
    ReplayPageOutput:
      type: object
      properties:
        url:
          type: string
        timestamp:
          type: number
        duration:
          type: number
        actions:
          type: array
          items:
            $ref: '#/components/schemas/ReplayActionOutput'
      required:
        - url
        - timestamp
        - duration
        - actions
      additionalProperties: false
    ReplayResultOutput:
      type: object
      properties:
        pages:
          type: array
          items:
            $ref: '#/components/schemas/ReplayPageOutput'
        clientLanguage:
          type: string
      required:
        - pages
      additionalProperties: false
    StreamEventSystemDataOutput:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StreamEventStatus'
        result:
          description: Operation result (present when status is 'finished')
          x-stainless-any: true
        error:
          description: Error message (present when status is 'error')
          type: string
      required:
        - status
      additionalProperties: false
    StreamEventLogDataOutput:
      type: object
      properties:
        status:
          type: string
          const: running
        message:
          description: Log message from the operation
          type: string
      required:
        - status
        - message
      additionalProperties: false
    ModelAuth:
      oneOf:
        - $ref: '#/components/schemas/GoogleServiceAccountAuth'
        - $ref: '#/components/schemas/AzureEntraIdAuth'
      type: object
      discriminator:
        propertyName: type
        mapping:
          googleServiceAccount: '#/components/schemas/GoogleServiceAccountAuth'
          azureEntraId: '#/components/schemas/AzureEntraIdAuth'
    ModelProviderOptions:
      anyOf:
        - $ref: '#/components/schemas/VertexModelProviderOptions'
        - $ref: '#/components/schemas/AzureModelProviderOptions'
    SessionIdParams:
      type: object
      properties:
        id:
          description: Unique session identifier
          example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
          type: string
      required:
        - id
      additionalProperties: false
    SessionHeaders:
      type: object
      properties:
        x-stream-response:
          description: Whether to stream the response via SSE
          example: 'true'
          type: string
          enum:
            - 'true'
            - 'false'
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
        code:
          type: string
      required:
        - success
        - error
      additionalProperties: false
    SessionEndResult:
      type: object
      properties: {}
      additionalProperties: false
    StreamEvent:
      description: >-
        Server-Sent Event emitted during streaming responses. Events are sent as
        `event: <status>\ndata: <JSON>\n\n`, where the JSON payload has the
        shape `{ data, type, id }`.
      type: object
      properties:
        data:
          anyOf:
            - $ref: '#/components/schemas/StreamEventSystemDataOutput'
            - $ref: '#/components/schemas/StreamEventLogDataOutput'
        type:
          $ref: '#/components/schemas/StreamEventType'
        id:
          description: Unique identifier for this event
          example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      required:
        - data
        - type
        - id
      additionalProperties: false
paths:
  /v1/sessions/{id}/act:
    post:
      operationId: SessionAct
      summary: Perform an action
      description: >-
        Executes a browser action using natural language instructions or a
        predefined Action object.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActRequest'
        required: true
      parameters:
        - schema:
            description: Unique session identifier
            example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
            type: string
          in: path
          name: id
          required: true
          description: Unique session identifier
        - schema:
            description: Whether to stream the response via SSE
            example: 'true'
            type: string
            enum:
              - 'true'
              - 'false'
          in: header
          name: x-stream-response
          description: Whether to stream the response via SSE
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Stagehand from 'stagehand-sdk';


            const client = new Stagehand({
              browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
              browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted
              modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted
            });


            const response = await
            client.sessions.act('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', {
              input: 'Click the login button',
            });


            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from stagehand import Stagehand

            client = Stagehand(
                browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),  # This is the default and can be omitted
                browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),  # This is the default and can be omitted
                model_api_key=os.environ.get("MODEL_API_KEY"),  # This is the default and can be omitted
            )
            for session in client.sessions.act(
                id="c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
                input="Click the login button",
            ):
              print(session)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Act(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionActParams{\n\t\t\tInput: stagehand.SessionActParamsInputUnion{\n\t\t\t\tOfString: stagehand.String(\"Click the login button\"),\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n"
        - lang: Java
          source: |-
            package com.browserbase.api.example;

            import com.browserbase.api.client.StagehandClient;
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
            import com.browserbase.api.models.sessions.SessionActParams;
            import com.browserbase.api.models.sessions.SessionActResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    StagehandClient client = StagehandOkHttpClient.fromEnv();

                    SessionActParams params = SessionActParams.builder()
                        .id("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")
                        .input("Click the login button")
                        .build();
                    SessionActResponse response = client.sessions().act(params);
                }
            }
        - lang: Kotlin
          source: |-
            package com.browserbase.api.example

            import com.browserbase.api.client.StagehandClient
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient
            import com.browserbase.api.models.sessions.SessionActParams
            import com.browserbase.api.models.sessions.SessionActResponse

            fun main() {
                val client: StagehandClient = StagehandOkHttpClient.fromEnv()

                val params: SessionActParams = SessionActParams.builder()
                    .id("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")
                    .input("Click the login button")
                    .build()
                val response: SessionActResponse = client.sessions().act(params)
            }
        - lang: Ruby
          source: >-
            require "stagehand"


            stagehand = Stagehand::Client.new(
              browserbase_api_key: "My Browserbase API Key",
              browserbase_project_id: "My Browserbase Project ID",
              model_api_key: "My Model API Key"
            )


            response =
            stagehand.sessions.act("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
            input: "Click the login button")


            puts(response)
        - lang: PHP
          source: |-
            <?php

            require_once dirname(__DIR__) . '/vendor/autoload.php';

            use Stagehand\Client;
            use Stagehand\Core\Exceptions\APIException;

            $client = new Client(
              browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: 'My Browserbase API Key',
              browserbaseProjectID: getenv(
                'BROWSERBASE_PROJECT_ID'
              ) ?: 'My Browserbase Project ID',
              modelAPIKey: getenv('MODEL_API_KEY') ?: 'My Model API Key',
            );

            try {
              $response = $client->sessions->act(
                'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',
                input: 'Click the login button',
                frameID: 'frameId',
                options: [
                  'model' => [
                    'auth' => [
                      'credentials' => [
                        'clientEmail' => 'client_email',
                        'privateKey' => 'private_key',
                        'authProviderX509CertURL' => 'https://example.com',
                        'authUri' => 'https://example.com',
                        'clientID' => 'client_id',
                        'clientX509CertURL' => 'https://example.com',
                        'privateKeyID' => 'private_key_id',
                        'projectID' => 'project_id',
                        'tokenUri' => 'https://example.com',
                        'type' => 'service_account',
                        'universeDomain' => 'universe_domain',
                      ],
                      'type' => 'googleServiceAccount',
                      'projectID' => 'projectId',
                      'scopes' => 'string',
                      'universeDomain' => 'universeDomain',
                    ],
                    'modelName' => 'openai/gpt-5.4-mini',
                    'provider' => 'vertex',
                    'providerOptions' => [
                      'vertex' => [
                        'location' => 'us-central1',
                        'project' => 'my-gcp-project',
                        'baseURL' => 'https://example.com',
                        'headers' => ['foo' => 'string'],
                      ],
                    ],
                    'apiKey' => 'sk-some-openai-api-key',
                    'baseURL' => 'https://api.openai.com/v1',
                    'headers' => ['foo' => 'string'],
                  ],
                  'timeout' => 30000,
                  'variables' => [
                    'username' => 'john_doe',
                    'password' => [
                      'value' => 'secret123', 'description' => 'The login password'
                    ],
                  ],
                ],
                xStreamResponse: 'true',
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: |-
            using System;
            using Stagehand;
            using Stagehand.Models.Sessions;

            StagehandClient client = new();

            SessionActParams parameters = new()
            {
                ID = "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
                Input = "Click the login button",
            };

            var response = await client.Sessions.Act(parameters);

            Console.WriteLine(response);
  /v1/sessions/{id}/end:
    post:
      operationId: SessionEnd
      summary: End a browser session
      description: Terminates the browser session and releases all associated resources.
      parameters:
        - schema:
            description: Unique session identifier
            example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
            type: string
          in: path
          name: id
          required: true
          description: Unique session identifier
        - schema:
            description: Whether to stream the response via SSE
            example: 'true'
            type: string
            enum:
              - 'true'
              - 'false'
          in: header
          name: x-stream-response
          description: Whether to stream the response via SSE
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionEndResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Stagehand from 'stagehand-sdk';


            const client = new Stagehand({
              browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
              browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted
              modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted
            });


            const response = await
            client.sessions.end('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123');


            console.log(response.success);
        - lang: Python
          source: |-
            import os
            from stagehand import Stagehand

            client = Stagehand(
                browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),  # This is the default and can be omitted
                browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),  # This is the default and can be omitted
                model_api_key=os.environ.get("MODEL_API_KEY"),  # This is the default and can be omitted
            )
            response = client.sessions.end(
                id="c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
            )
            print(response.success)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.End(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionEndParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Success)\n}\n"
        - lang: Java
          source: |-
            package com.browserbase.api.example;

            import com.browserbase.api.client.StagehandClient;
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
            import com.browserbase.api.models.sessions.SessionEndParams;
            import com.browserbase.api.models.sessions.SessionEndResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    StagehandClient client = StagehandOkHttpClient.fromEnv();

                    SessionEndResponse response = client.sessions().end("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123");
                }
            }
        - lang: Kotlin
          source: |-
            package com.browserbase.api.example

            import com.browserbase.api.client.StagehandClient
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient
            import com.browserbase.api.models.sessions.SessionEndParams
            import com.browserbase.api.models.sessions.SessionEndResponse

            fun main() {
                val client: StagehandClient = StagehandOkHttpClient.fromEnv()

                val response: SessionEndResponse = client.sessions().end("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")
            }
        - lang: Ruby
          source: >-
            require "stagehand"


            stagehand = Stagehand::Client.new(
              browserbase_api_key: "My Browserbase API Key",
              browserbase_project_id: "My Browserbase Project ID",
              model_api_key: "My Model API Key"
            )


            response =
            stagehand.sessions.end_("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")


            puts(response)
        - lang: PHP
          source: |-
            <?php

            require_once dirname(__DIR__) . '/vendor/autoload.php';

            use Stagehand\Client;
            use Stagehand\Core\Exceptions\APIException;

            $client = new Client(
              browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: 'My Browserbase API Key',
              browserbaseProjectID: getenv(
                'BROWSERBASE_PROJECT_ID'
              ) ?: 'My Browserbase Project ID',
              modelAPIKey: getenv('MODEL_API_KEY') ?: 'My Model API Key',
            );

            try {
              $response = $client->sessions->end(
                'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', xStreamResponse: 'true'
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: |-
            using System;
            using Stagehand;
            using Stagehand.Models.Sessions;

            StagehandClient client = new();

            SessionEndParams parameters = new()
            {
                ID = "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123"
            };

            var response = await client.Sessions.End(parameters);

            Console.WriteLine(response);
  /v1/sessions/{id}/extract:
    post:
      operationId: SessionExtract
      summary: Extract data from the page
      description: >-
        Extracts structured data from the current page using AI-powered
        analysis.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractRequest'
        required: true
      parameters:
        - schema:
            description: Unique session identifier
            example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
            type: string
          in: path
          name: id
          required: true
          description: Unique session identifier
        - schema:
            description: Whether to stream the response via SSE
            example: 'true'
            type: string
            enum:
              - 'true'
              - 'false'
          in: header
          name: x-stream-response
          description: Whether to stream the response via SSE
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Stagehand from 'stagehand-sdk';


            const client = new Stagehand({
              browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
              browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted
              modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted
            });


            const response = await
            client.sessions.extract('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123');


            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from stagehand import Stagehand

            client = Stagehand(
                browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),  # This is the default and can be omitted
                browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),  # This is the default and can be omitted
                model_api_key=os.environ.get("MODEL_API_KEY"),  # This is the default and can be omitted
            )
            for session in client.sessions.extract(
                id="c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
            ):
              print(session)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Extract(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionExtractParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n"
        - lang: Java
          source: |-
            package com.browserbase.api.example;

            import com.browserbase.api.client.StagehandClient;
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
            import com.browserbase.api.models.sessions.SessionExtractParams;
            import com.browserbase.api.models.sessions.SessionExtractResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    StagehandClient client = StagehandOkHttpClient.fromEnv();

                    SessionExtractResponse response = client.sessions().extract("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123");
                }
            }
        - lang: Kotlin
          source: |-
            package com.browserbase.api.example

            import com.browserbase.api.client.StagehandClient
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient
            import com.browserbase.api.models.sessions.SessionExtractParams
            import com.browserbase.api.models.sessions.SessionExtractResponse

            fun main() {
                val client: StagehandClient = StagehandOkHttpClient.fromEnv()

                val response: SessionExtractResponse = client.sessions().extract("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")
            }
        - lang: Ruby
          source: >-
            require "stagehand"


            stagehand = Stagehand::Client.new(
              browserbase_api_key: "My Browserbase API Key",
              browserbase_project_id: "My Browserbase Project ID",
              model_api_key: "My Model API Key"
            )


            response =
            stagehand.sessions.extract("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")


            puts(response)
        - lang: PHP
          source: |-
            <?php

            require_once dirname(__DIR__) . '/vendor/autoload.php';

            use Stagehand\Client;
            use Stagehand\Core\Exceptions\APIException;

            $client = new Client(
              browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: 'My Browserbase API Key',
              browserbaseProjectID: getenv(
                'BROWSERBASE_PROJECT_ID'
              ) ?: 'My Browserbase Project ID',
              modelAPIKey: getenv('MODEL_API_KEY') ?: 'My Model API Key',
            );

            try {
              $response = $client->sessions->extract(
                'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',
                frameID: 'frameId',
                instruction: 'Extract all product names and prices from the page',
                options: [
                  'ignoreSelectors' => ['nav', '.cookie-banner', '#sidebar-ads'],
                  'model' => [
                    'auth' => [
                      'credentials' => [
                        'clientEmail' => 'client_email',
                        'privateKey' => 'private_key',
                        'authProviderX509CertURL' => 'https://example.com',
                        'authUri' => 'https://example.com',
                        'clientID' => 'client_id',
                        'clientX509CertURL' => 'https://example.com',
                        'privateKeyID' => 'private_key_id',
                        'projectID' => 'project_id',
                        'tokenUri' => 'https://example.com',
                        'type' => 'service_account',
                        'universeDomain' => 'universe_domain',
                      ],
                      'type' => 'googleServiceAccount',
                      'projectID' => 'projectId',
                      'scopes' => 'string',
                      'universeDomain' => 'universeDomain',
                    ],
                    'modelName' => 'openai/gpt-5.4-mini',
                    'provider' => 'vertex',
                    'providerOptions' => [
                      'vertex' => [
                        'location' => 'us-central1',
                        'project' => 'my-gcp-project',
                        'baseURL' => 'https://example.com',
                        'headers' => ['foo' => 'string'],
                      ],
                    ],
                    'apiKey' => 'sk-some-openai-api-key',
                    'baseURL' => 'https://api.openai.com/v1',
                    'headers' => ['foo' => 'string'],
                  ],
                  'screenshot' => false,
                  'selector' => '#main-content',
                  'timeout' => 30000,
                ],
                schema: ['foo' => 'bar'],
                xStreamResponse: 'true',
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: |-
            using System;
            using Stagehand;
            using Stagehand.Models.Sessions;

            StagehandClient client = new();

            SessionExtractParams parameters = new()
            {
                ID = "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123"
            };

            var response = await client.Sessions.Extract(parameters);

            Console.WriteLine(response);
  /v1/sessions/{id}/navigate:
    post:
      operationId: SessionNavigate
      summary: Navigate to a URL
      description: Navigates the browser to the specified URL.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NavigateRequest'
        required: true
      parameters:
        - schema:
            description: Unique session identifier
            example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
            type: string
          in: path
          name: id
          required: true
          description: Unique session identifier
        - schema:
            description: Whether to stream the response via SSE
            example: 'true'
            type: string
            enum:
              - 'true'
              - 'false'
          in: header
          name: x-stream-response
          description: Whether to stream the response via SSE
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavigateResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Stagehand from 'stagehand-sdk';


            const client = new Stagehand({
              browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
              browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted
              modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted
            });


            const response = await
            client.sessions.navigate('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', {
              url: 'https://example.com',
            });


            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from stagehand import Stagehand

            client = Stagehand(
                browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),  # This is the default and can be omitted
                browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),  # This is the default and can be omitted
                model_api_key=os.environ.get("MODEL_API_KEY"),  # This is the default and can be omitted
            )
            response = client.sessions.navigate(
                id="c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
                url="https://example.com",
            )
            print(response.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Navigate(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionNavigateParams{\n\t\t\tURL: \"https://example.com\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n"
        - lang: Java
          source: |-
            package com.browserbase.api.example;

            import com.browserbase.api.client.StagehandClient;
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
            import com.browserbase.api.models.sessions.SessionNavigateParams;
            import com.browserbase.api.models.sessions.SessionNavigateResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    StagehandClient client = StagehandOkHttpClient.fromEnv();

                    SessionNavigateParams params = SessionNavigateParams.builder()
                        .id("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")
                        .url("https://example.com")
                        .build();
                    SessionNavigateResponse response = client.sessions().navigate(params);
                }
            }
        - lang: Kotlin
          source: |-
            package com.browserbase.api.example

            import com.browserbase.api.client.StagehandClient
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient
            import com.browserbase.api.models.sessions.SessionNavigateParams
            import com.browserbase.api.models.sessions.SessionNavigateResponse

            fun main() {
                val client: StagehandClient = StagehandOkHttpClient.fromEnv()

                val params: SessionNavigateParams = SessionNavigateParams.builder()
                    .id("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")
                    .url("https://example.com")
                    .build()
                val response: SessionNavigateResponse = client.sessions().navigate(params)
            }
        - lang: Ruby
          source: >-
            require "stagehand"


            stagehand = Stagehand::Client.new(
              browserbase_api_key: "My Browserbase API Key",
              browserbase_project_id: "My Browserbase Project ID",
              model_api_key: "My Model API Key"
            )


            response =
            stagehand.sessions.navigate("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
            url: "https://example.com")


            puts(response)
        - lang: PHP
          source: |-
            <?php

            require_once dirname(__DIR__) . '/vendor/autoload.php';

            use Stagehand\Client;
            use Stagehand\Core\Exceptions\APIException;

            $client = new Client(
              browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: 'My Browserbase API Key',
              browserbaseProjectID: getenv(
                'BROWSERBASE_PROJECT_ID'
              ) ?: 'My Browserbase Project ID',
              modelAPIKey: getenv('MODEL_API_KEY') ?: 'My Model API Key',
            );

            try {
              $response = $client->sessions->navigate(
                'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',
                url: 'https://example.com',
                frameID: 'frameId',
                options: [
                  'referer' => 'referer', 'timeout' => 30000, 'waitUntil' => 'networkidle'
                ],
                streamResponse: true,
                xStreamResponse: 'true',
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: |-
            using System;
            using Stagehand;
            using Stagehand.Models.Sessions;

            StagehandClient client = new();

            SessionNavigateParams parameters = new()
            {
                ID = "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
                UrlValue = "https://example.com",
            };

            var response = await client.Sessions.Navigate(parameters);

            Console.WriteLine(response);
  /v1/sessions/{id}/observe:
    post:
      operationId: SessionObserve
      summary: Observe available actions
      description: >-
        Identifies and returns available actions on the current page that match
        the given instruction.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObserveRequest'
        required: true
      parameters:
        - schema:
            description: Unique session identifier
            example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
            type: string
          in: path
          name: id
          required: true
          description: Unique session identifier
        - schema:
            description: Whether to stream the response via SSE
            example: 'true'
            type: string
            enum:
              - 'true'
              - 'false'
          in: header
          name: x-stream-response
          description: Whether to stream the response via SSE
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObserveResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Stagehand from 'stagehand-sdk';


            const client = new Stagehand({
              browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
              browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted
              modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted
            });


            const response = await
            client.sessions.observe('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123');


            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from stagehand import Stagehand

            client = Stagehand(
                browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),  # This is the default and can be omitted
                browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),  # This is the default and can be omitted
                model_api_key=os.environ.get("MODEL_API_KEY"),  # This is the default and can be omitted
            )
            for session in client.sessions.observe(
                id="c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
            ):
              print(session)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Observe(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionObserveParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n"
        - lang: Java
          source: |-
            package com.browserbase.api.example;

            import com.browserbase.api.client.StagehandClient;
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
            import com.browserbase.api.models.sessions.SessionObserveParams;
            import com.browserbase.api.models.sessions.SessionObserveResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    StagehandClient client = StagehandOkHttpClient.fromEnv();

                    SessionObserveResponse response = client.sessions().observe("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123");
                }
            }
        - lang: Kotlin
          source: |-
            package com.browserbase.api.example

            import com.browserbase.api.client.StagehandClient
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient
            import com.browserbase.api.models.sessions.SessionObserveParams
            import com.browserbase.api.models.sessions.SessionObserveResponse

            fun main() {
                val client: StagehandClient = StagehandOkHttpClient.fromEnv()

                val response: SessionObserveResponse = client.sessions().observe("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")
            }
        - lang: Ruby
          source: >-
            require "stagehand"


            stagehand = Stagehand::Client.new(
              browserbase_api_key: "My Browserbase API Key",
              browserbase_project_id: "My Browserbase Project ID",
              model_api_key: "My Model API Key"
            )


            response =
            stagehand.sessions.observe("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")


            puts(response)
        - lang: PHP
          source: |-
            <?php

            require_once dirname(__DIR__) . '/vendor/autoload.php';

            use Stagehand\Client;
            use Stagehand\Core\Exceptions\APIException;

            $client = new Client(
              browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: 'My Browserbase API Key',
              browserbaseProjectID: getenv(
                'BROWSERBASE_PROJECT_ID'
              ) ?: 'My Browserbase Project ID',
              modelAPIKey: getenv('MODEL_API_KEY') ?: 'My Model API Key',
            );

            try {
              $response = $client->sessions->observe(
                'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',
                frameID: 'frameId',
                instruction: 'Find all clickable navigation links',
                options: [
                  'ignoreSelectors' => ['nav', '.cookie-banner', '#sidebar-ads'],
                  'model' => [
                    'auth' => [
                      'credentials' => [
                        'clientEmail' => 'client_email',
                        'privateKey' => 'private_key',
                        'authProviderX509CertURL' => 'https://example.com',
                        'authUri' => 'https://example.com',
                        'clientID' => 'client_id',
                        'clientX509CertURL' => 'https://example.com',
                        'privateKeyID' => 'private_key_id',
                        'projectID' => 'project_id',
                        'tokenUri' => 'https://example.com',
                        'type' => 'service_account',
                        'universeDomain' => 'universe_domain',
                      ],
                      'type' => 'googleServiceAccount',
                      'projectID' => 'projectId',
                      'scopes' => 'string',
                      'universeDomain' => 'universeDomain',
                    ],
                    'modelName' => 'openai/gpt-5.4-mini',
                    'provider' => 'vertex',
                    'providerOptions' => [
                      'vertex' => [
                        'location' => 'us-central1',
                        'project' => 'my-gcp-project',
                        'baseURL' => 'https://example.com',
                        'headers' => ['foo' => 'string'],
                      ],
                    ],
                    'apiKey' => 'sk-some-openai-api-key',
                    'baseURL' => 'https://api.openai.com/v1',
                    'headers' => ['foo' => 'string'],
                  ],
                  'selector' => 'nav',
                  'timeout' => 30000,
                  'variables' => [
                    'username' => [
                      'value' => 'john@example.com', 'description' => 'The login email'
                    ],
                    'rememberMe' => true,
                  ],
                ],
                xStreamResponse: 'true',
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: |-
            using System;
            using Stagehand;
            using Stagehand.Models.Sessions;

            StagehandClient client = new();

            SessionObserveParams parameters = new()
            {
                ID = "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123"
            };

            var response = await client.Sessions.Observe(parameters);

            Console.WriteLine(response);
  /v1/sessions/{id}/replay:
    get:
      operationId: SessionReplay
      summary: Replay session metrics
      description: Retrieves replay metrics for a session.
      parameters:
        - schema:
            description: Unique session identifier
            example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
            type: string
          in: path
          name: id
          required: true
          description: Unique session identifier
        - schema:
            description: Whether to stream the response via SSE
            example: 'true'
            type: string
            enum:
              - 'true'
              - 'false'
          in: header
          name: x-stream-response
          description: Whether to stream the response via SSE
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplayResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Stagehand from 'stagehand-sdk';


            const client = new Stagehand({
              browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
              browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted
              modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted
            });


            const response = await
            client.sessions.replay('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123');


            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from stagehand import Stagehand

            client = Stagehand(
                browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),  # This is the default and can be omitted
                browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),  # This is the default and can be omitted
                model_api_key=os.environ.get("MODEL_API_KEY"),  # This is the default and can be omitted
            )
            response = client.sessions.replay(
                id="c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
            )
            print(response.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Replay(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionReplayParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n"
        - lang: Java
          source: |-
            package com.browserbase.api.example;

            import com.browserbase.api.client.StagehandClient;
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
            import com.browserbase.api.models.sessions.SessionReplayParams;
            import com.browserbase.api.models.sessions.SessionReplayResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    StagehandClient client = StagehandOkHttpClient.fromEnv();

                    SessionReplayResponse response = client.sessions().replay("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123");
                }
            }
        - lang: Kotlin
          source: |-
            package com.browserbase.api.example

            import com.browserbase.api.client.StagehandClient
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient
            import com.browserbase.api.models.sessions.SessionReplayParams
            import com.browserbase.api.models.sessions.SessionReplayResponse

            fun main() {
                val client: StagehandClient = StagehandOkHttpClient.fromEnv()

                val response: SessionReplayResponse = client.sessions().replay("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")
            }
        - lang: Ruby
          source: >-
            require "stagehand"


            stagehand = Stagehand::Client.new(
              browserbase_api_key: "My Browserbase API Key",
              browserbase_project_id: "My Browserbase Project ID",
              model_api_key: "My Model API Key"
            )


            response =
            stagehand.sessions.replay("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")


            puts(response)
        - lang: PHP
          source: |-
            <?php

            require_once dirname(__DIR__) . '/vendor/autoload.php';

            use Stagehand\Client;
            use Stagehand\Core\Exceptions\APIException;

            $client = new Client(
              browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: 'My Browserbase API Key',
              browserbaseProjectID: getenv(
                'BROWSERBASE_PROJECT_ID'
              ) ?: 'My Browserbase Project ID',
              modelAPIKey: getenv('MODEL_API_KEY') ?: 'My Model API Key',
            );

            try {
              $response = $client->sessions->replay(
                'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', xStreamResponse: 'true'
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: |-
            using System;
            using Stagehand;
            using Stagehand.Models.Sessions;

            StagehandClient client = new();

            SessionReplayParams parameters = new()
            {
                ID = "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123"
            };

            var response = await client.Sessions.Replay(parameters);

            Console.WriteLine(response);
  /v1/sessions/start:
    post:
      operationId: SessionStart
      summary: Start a new browser session
      description: >-
        Creates a new browser session with the specified configuration. Returns
        a session ID used for all subsequent operations.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionStartRequest'
        required: true
      parameters:
        - schema:
            description: Whether to stream the response via SSE
            example: 'true'
            type: string
            enum:
              - 'true'
              - 'false'
          in: header
          name: x-stream-response
          description: Whether to stream the response via SSE
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionStartResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Stagehand from 'stagehand-sdk';


            const client = new Stagehand({
              browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
              browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted
              modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted
            });


            const response = await client.sessions.start({ modelName:
            'openai/gpt-5.4-mini' });


            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from stagehand import Stagehand

            client = Stagehand(
                browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),  # This is the default and can be omitted
                browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),  # This is the default and can be omitted
                model_api_key=os.environ.get("MODEL_API_KEY"),  # This is the default and can be omitted
            )
            response = client.sessions.start(
                model_name="openai/gpt-5.4-mini",
            )
            print(response.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Start(context.TODO(), stagehand.SessionStartParams{\n\t\tModelName: \"openai/gpt-5.4-mini\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n"
        - lang: Java
          source: |-
            package com.browserbase.api.example;

            import com.browserbase.api.client.StagehandClient;
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
            import com.browserbase.api.models.sessions.SessionStartParams;
            import com.browserbase.api.models.sessions.SessionStartResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    StagehandClient client = StagehandOkHttpClient.fromEnv();

                    SessionStartParams params = SessionStartParams.builder()
                        .modelName("openai/gpt-5.4-mini")
                        .build();
                    SessionStartResponse response = client.sessions().start(params);
                }
            }
        - lang: Kotlin
          source: |-
            package com.browserbase.api.example

            import com.browserbase.api.client.StagehandClient
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient
            import com.browserbase.api.models.sessions.SessionStartParams
            import com.browserbase.api.models.sessions.SessionStartResponse

            fun main() {
                val client: StagehandClient = StagehandOkHttpClient.fromEnv()

                val params: SessionStartParams = SessionStartParams.builder()
                    .modelName("openai/gpt-5.4-mini")
                    .build()
                val response: SessionStartResponse = client.sessions().start(params)
            }
        - lang: Ruby
          source: >-
            require "stagehand"


            stagehand = Stagehand::Client.new(
              browserbase_api_key: "My Browserbase API Key",
              browserbase_project_id: "My Browserbase Project ID",
              model_api_key: "My Model API Key"
            )


            response = stagehand.sessions.start(model_name:
            "openai/gpt-5.4-mini")


            puts(response)
        - lang: PHP
          source: |-
            <?php

            require_once dirname(__DIR__) . '/vendor/autoload.php';

            use Stagehand\Client;
            use Stagehand\Core\Exceptions\APIException;

            $client = new Client(
              browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: 'My Browserbase API Key',
              browserbaseProjectID: getenv(
                'BROWSERBASE_PROJECT_ID'
              ) ?: 'My Browserbase Project ID',
              modelAPIKey: getenv('MODEL_API_KEY') ?: 'My Model API Key',
            );

            try {
              $response = $client->sessions->start(
                modelName: 'openai/gpt-5.4-mini',
                actTimeoutMs: 0,
                browser: [
                  'cdpURL' => 'ws://localhost:9222',
                  'launchOptions' => [
                    'acceptDownloads' => true,
                    'args' => ['string'],
                    'cdpHeaders' => ['foo' => 'string'],
                    'cdpURL' => 'cdpUrl',
                    'chromiumSandbox' => true,
                    'connectTimeoutMs' => 0,
                    'deviceScaleFactor' => 0,
                    'devtools' => true,
                    'downloadsPath' => 'downloadsPath',
                    'executablePath' => 'executablePath',
                    'hasTouch' => true,
                    'headless' => true,
                    'ignoreDefaultArgs' => true,
                    'ignoreHTTPSErrors' => true,
                    'locale' => 'locale',
                    'port' => 0,
                    'preserveUserDataDir' => true,
                    'proxy' => [
                      'server' => 'server',
                      'bypass' => 'bypass',
                      'password' => 'password',
                      'username' => 'username',
                    ],
                    'userDataDir' => 'userDataDir',
                    'viewport' => ['height' => 0, 'width' => 0],
                  ],
                  'type' => 'local',
                ],
                browserbaseSessionCreateParams: [
                  'browserSettings' => [
                    'advancedStealth' => true,
                    'blockAds' => true,
                    'captchaImageSelector' => 'captchaImageSelector',
                    'captchaInputSelector' => 'captchaInputSelector',
                    'context' => ['id' => 'id', 'persist' => true],
                    'extensionID' => 'extensionId',
                    'fingerprint' => [
                      'browsers' => ['chrome'],
                      'devices' => ['desktop'],
                      'httpVersion' => '1',
                      'locales' => ['string'],
                      'operatingSystems' => ['android'],
                      'screen' => [
                        'maxHeight' => 0, 'maxWidth' => 0, 'minHeight' => 0, 'minWidth' => 0
                      ],
                    ],
                    'logSession' => true,
                    'os' => 'windows',
                    'recordSession' => true,
                    'solveCaptchas' => true,
                    'verified' => true,
                    'viewport' => ['height' => 0, 'width' => 0],
                  ],
                  'extensionID' => 'extensionId',
                  'keepAlive' => true,
                  'projectID' => 'projectId',
                  'proxies' => true,
                  'region' => 'us-west-2',
                  'timeout' => 0,
                  'userMetadata' => ['foo' => 'bar'],
                ],
                browserbaseSessionID: 'browserbaseSessionID',
                domSettleTimeoutMs: 5000,
                experimental: true,
                selfHeal: true,
                systemPrompt: 'systemPrompt',
                verbose: 1,
                waitForCaptchaSolves: true,
                xStreamResponse: 'true',
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: >-
            using System;

            using Stagehand;

            using Stagehand.Models.Sessions;


            StagehandClient client = new();


            SessionStartParams parameters = new() { ModelName =
            "openai/gpt-5.4-mini" };


            var response = await client.Sessions.Start(parameters);


            Console.WriteLine(response);
  /v1/sessions/{id}/agentExecute:
    post:
      operationId: SessionAgentExecute
      summary: Execute an AI agent
      description: >-
        Runs an autonomous AI agent that can perform complex multi-step browser
        tasks.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentExecuteRequest'
        required: true
      parameters:
        - schema:
            description: Unique session identifier
            example: c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123
            type: string
          in: path
          name: id
          required: true
          description: Unique session identifier
        - schema:
            description: Whether to stream the response via SSE
            example: 'true'
            type: string
            enum:
              - 'true'
              - 'false'
          in: header
          name: x-stream-response
          description: Whether to stream the response via SSE
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentExecuteResponse'
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Stagehand from 'stagehand-sdk';


            const client = new Stagehand({
              browserbaseAPIKey: process.env['BROWSERBASE_API_KEY'], // This is the default and can be omitted
              browserbaseProjectID: process.env['BROWSERBASE_PROJECT_ID'], // This is the default and can be omitted
              modelAPIKey: process.env['MODEL_API_KEY'], // This is the default and can be omitted
            });


            const response = await
            client.sessions.execute('c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123', {
              agentConfig: {},
              executeOptions: {
                instruction: "Log in with username 'demo' and password 'test123', then navigate to settings",
              },
            });


            console.log(response.data);
        - lang: Python
          source: |-
            import os
            from stagehand import Stagehand

            client = Stagehand(
                browserbase_api_key=os.environ.get("BROWSERBASE_API_KEY"),  # This is the default and can be omitted
                browserbase_project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),  # This is the default and can be omitted
                model_api_key=os.environ.get("MODEL_API_KEY"),  # This is the default and can be omitted
            )
            for session in client.sessions.execute(
                id="c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
                agent_config={},
                execute_options={
                    "instruction": "Log in with username 'demo' and password 'test123', then navigate to settings"
                },
            ):
              print(session)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/browserbase/stagehand-go\"\n\t\"github.com/browserbase/stagehand-go/option\"\n)\n\nfunc main() {\n\tclient := stagehand.NewClient(\n\t\toption.WithBrowserbaseAPIKey(\"My Browserbase API Key\"),\n\t\toption.WithBrowserbaseProjectID(\"My Browserbase Project ID\"),\n\t\toption.WithModelAPIKey(\"My Model API Key\"),\n\t)\n\tresponse, err := client.Sessions.Execute(\n\t\tcontext.TODO(),\n\t\t\"c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123\",\n\t\tstagehand.SessionExecuteParams{\n\t\t\tAgentConfig: stagehand.SessionExecuteParamsAgentConfig{},\n\t\t\tExecuteOptions: stagehand.SessionExecuteParamsExecuteOptions{\n\t\t\t\tInstruction: \"Log in with username 'demo' and password 'test123', then navigate to settings\",\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n"
        - lang: Java
          source: |-
            package com.browserbase.api.example;

            import com.browserbase.api.client.StagehandClient;
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
            import com.browserbase.api.models.sessions.SessionExecuteParams;
            import com.browserbase.api.models.sessions.SessionExecuteResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    StagehandClient client = StagehandOkHttpClient.fromEnv();

                    SessionExecuteParams params = SessionExecuteParams.builder()
                        .id("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")
                        .agentConfig(SessionExecuteParams.AgentConfig.builder().build())
                        .executeOptions(SessionExecuteParams.ExecuteOptions.builder()
                            .instruction("Log in with username 'demo' and password 'test123', then navigate to settings")
                            .build())
                        .build();
                    SessionExecuteResponse response = client.sessions().execute(params);
                }
            }
        - lang: Kotlin
          source: |-
            package com.browserbase.api.example

            import com.browserbase.api.client.StagehandClient
            import com.browserbase.api.client.okhttp.StagehandOkHttpClient
            import com.browserbase.api.models.sessions.SessionExecuteParams
            import com.browserbase.api.models.sessions.SessionExecuteResponse

            fun main() {
                val client: StagehandClient = StagehandOkHttpClient.fromEnv()

                val params: SessionExecuteParams = SessionExecuteParams.builder()
                    .id("c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123")
                    .agentConfig(SessionExecuteParams.AgentConfig.builder().build())
                    .executeOptions(SessionExecuteParams.ExecuteOptions.builder()
                        .instruction("Log in with username 'demo' and password 'test123', then navigate to settings")
                        .build())
                    .build()
                val response: SessionExecuteResponse = client.sessions().execute(params)
            }
        - lang: Ruby
          source: |-
            require "stagehand"

            stagehand = Stagehand::Client.new(
              browserbase_api_key: "My Browserbase API Key",
              browserbase_project_id: "My Browserbase Project ID",
              model_api_key: "My Model API Key"
            )

            response = stagehand.sessions.execute(
              "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
              agent_config: {},
              execute_options: {instruction: "Log in with username 'demo' and password 'test123', then navigate to settings"}
            )

            puts(response)
        - lang: PHP
          source: |-
            <?php

            require_once dirname(__DIR__) . '/vendor/autoload.php';

            use Stagehand\Client;
            use Stagehand\Core\Exceptions\APIException;

            $client = new Client(
              browserbaseAPIKey: getenv('BROWSERBASE_API_KEY') ?: 'My Browserbase API Key',
              browserbaseProjectID: getenv(
                'BROWSERBASE_PROJECT_ID'
              ) ?: 'My Browserbase Project ID',
              modelAPIKey: getenv('MODEL_API_KEY') ?: 'My Model API Key',
            );

            try {
              $response = $client->sessions->execute(
                'c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123',
                agentConfig: [
                  'cua' => true,
                  'executionModel' => [
                    'auth' => [
                      'credentials' => [
                        'clientEmail' => 'client_email',
                        'privateKey' => 'private_key',
                        'authProviderX509CertURL' => 'https://example.com',
                        'authUri' => 'https://example.com',
                        'clientID' => 'client_id',
                        'clientX509CertURL' => 'https://example.com',
                        'privateKeyID' => 'private_key_id',
                        'projectID' => 'project_id',
                        'tokenUri' => 'https://example.com',
                        'type' => 'service_account',
                        'universeDomain' => 'universe_domain',
                      ],
                      'type' => 'googleServiceAccount',
                      'projectID' => 'projectId',
                      'scopes' => 'string',
                      'universeDomain' => 'universeDomain',
                    ],
                    'modelName' => 'openai/gpt-5.4-mini',
                    'provider' => 'vertex',
                    'providerOptions' => [
                      'vertex' => [
                        'location' => 'us-central1',
                        'project' => 'my-gcp-project',
                        'baseURL' => 'https://example.com',
                        'headers' => ['foo' => 'string'],
                      ],
                    ],
                    'apiKey' => 'sk-some-openai-api-key',
                    'baseURL' => 'https://api.openai.com/v1',
                    'headers' => ['foo' => 'string'],
                  ],
                  'mode' => 'cua',
                  'model' => [
                    'auth' => [
                      'credentials' => [
                        'clientEmail' => 'client_email',
                        'privateKey' => 'private_key',
                        'authProviderX509CertURL' => 'https://example.com',
                        'authUri' => 'https://example.com',
                        'clientID' => 'client_id',
                        'clientX509CertURL' => 'https://example.com',
                        'privateKeyID' => 'private_key_id',
                        'projectID' => 'project_id',
                        'tokenUri' => 'https://example.com',
                        'type' => 'service_account',
                        'universeDomain' => 'universe_domain',
                      ],
                      'type' => 'googleServiceAccount',
                      'projectID' => 'projectId',
                      'scopes' => 'string',
                      'universeDomain' => 'universeDomain',
                    ],
                    'modelName' => 'openai/gpt-5.4-mini',
                    'provider' => 'vertex',
                    'providerOptions' => [
                      'vertex' => [
                        'location' => 'us-central1',
                        'project' => 'my-gcp-project',
                        'baseURL' => 'https://example.com',
                        'headers' => ['foo' => 'string'],
                      ],
                    ],
                    'apiKey' => 'sk-some-openai-api-key',
                    'baseURL' => 'https://api.openai.com/v1',
                    'headers' => ['foo' => 'string'],
                  ],
                  'provider' => 'openai',
                  'systemPrompt' => 'systemPrompt',
                ],
                executeOptions: [
                  'instruction' => 'Log in with username \'demo\' and password \'test123\', then navigate to settings',
                  'highlightCursor' => true,
                  'maxSteps' => 20,
                  'toolTimeout' => 30000,
                  'useSearch' => true,
                  'variables' => ['foo' => 'string'],
                ],
                frameID: 'frameId',
                shouldCache: true,
                xStreamResponse: 'true',
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: |-
            using System;
            using System.Collections.Generic;
            using Stagehand;
            using Stagehand.Models.Sessions;

            StagehandClient client = new();

            SessionExecuteParams parameters = new()
            {
                ID = "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123",
                AgentConfig = new()
                {
                    Cua = true,
                    ExecutionModel = new ExecutionModelVertexModelConfigObject()
                    {
                        Auth = new()
                        {
                            Credentials = new()
                            {
                                ClientEmail = "client_email",
                                PrivateKey = "private_key",
                                AuthProviderX509CertUrl = "https://example.com",
                                AuthUri = "https://example.com",
                                ClientID = "client_id",
                                ClientX509CertUrl = "https://example.com",
                                PrivateKeyID = "private_key_id",
                                ProjectID = "project_id",
                                TokenUri = "https://example.com",
                                Type = ExecutionModelVertexModelConfigObjectAuthCredentialsType.ServiceAccount,
                                UniverseDomain = "universe_domain",
                            },
                            ProjectID = "projectId",
                            Scopes = "string",
                            UniverseDomain = "universeDomain",
                        },
                        ModelName = "openai/gpt-5.4-mini",
                        ProviderOptions = new(
                            new ExecutionModelVertexModelConfigObjectProviderOptionsVertex()
                            {
                                Location = "us-central1",
                                Project = "my-gcp-project",
                                BaseUrl = "https://example.com",
                                Headers = new Dictionary<string, string>()
                                {
                                    { "foo", "string" }
                                },
                            }
                        ),
                        ApiKey = "sk-some-openai-api-key",
                        BaseUrl = "https://api.openai.com/v1",
                        Headers = new Dictionary<string, string>() { { "foo", "string" } },
                    },
                    Mode = Mode.Cua,
                    Model = new AgentConfigModelVertexModelConfigObject()
                    {
                        Auth = new()
                        {
                            Credentials = new()
                            {
                                ClientEmail = "client_email",
                                PrivateKey = "private_key",
                                AuthProviderX509CertUrl = "https://example.com",
                                AuthUri = "https://example.com",
                                ClientID = "client_id",
                                ClientX509CertUrl = "https://example.com",
                                PrivateKeyID = "private_key_id",
                                ProjectID = "project_id",
                                TokenUri = "https://example.com",
                                Type = AgentConfigModelVertexModelConfigObjectAuthCredentialsType.ServiceAccount,
                                UniverseDomain = "universe_domain",
                            },
                            ProjectID = "projectId",
                            Scopes = "string",
                            UniverseDomain = "universeDomain",
                        },
                        ModelName = "openai/gpt-5.4-mini",
                        ProviderOptions = new(
                            new AgentConfigModelVertexModelConfigObjectProviderOptionsVertex(

                            )
                            {
                                Location = "us-central1",
                                Project = "my-gcp-project",
                                BaseUrl = "https://example.com",
                                Headers = new Dictionary<string, string>()
                                {
                                    { "foo", "string" }
                                },
                            }
                        ),
                        ApiKey = "sk-some-openai-api-key",
                        BaseUrl = "https://api.openai.com/v1",
                        Headers = new Dictionary<string, string>() { { "foo", "string" } },
                    },
                    Provider = AgentConfigProvider.OpenAI,
                    SystemPrompt = "systemPrompt",
                },
                ExecuteOptions = new()
                {
                    Instruction = "Log in with username 'demo' and password 'test123', then navigate to settings",
                    HighlightCursor = true,
                    MaxSteps = 20,
                    ToolTimeout = 30000,
                    UseSearch = true,
                    Variables = new Dictionary<string, ExecuteOptionsVariable>()
                    {
                        { "foo", "string" }
                    },
                },
            };

            var response = await client.Sessions.Execute(parameters);

            Console.WriteLine(response);
servers:
  - url: https://api.stagehand.browserbase.com
security:
  - BrowserbaseApiKey: []
    BrowserbaseProjectId: []
