docs(sdk): clarify regional baseUrl usage and deprecate request region

[BABTUNA]

What

Adds clearer documentation for using baseUrl / base_url / option.WithBaseURL() to select a regional Stagehand API endpoint in the generated Go, Java, Python, and Ruby SDK docs. Marks browserbaseSessionCreateParams.region as deprecated in the generated OpenAPI spec.

Why

For hosted Stagehand, the API endpoint the client calls is what determines the pod region. The hosted server overrides any client-provided browserbaseSessionCreateParams.region with the API instance's AWS_REGION, so baseUrl is the correct user-facing mechanism to document.

Changes

• Add Client configuration / baseUrl examples to Go, Java, Python, and Ruby SDK docs
• Add deprecation description + example for region in BrowserbaseSessionCreateParamsSchema
• Add the four regional Stagehand API endpoints to OpenAPI servers (us-west-2 default, us-east-1, eu-central-1, ap-southeast-1) for both server-v3 and server-v4
• Apply deprecated: true to region via Stainless patches so generated SDKs reflect the deprecation

Note

This is a revive of #1820 by @monadoid. Original PR was approved but went stale and conflicts with main. Rebased onto current main and resolved conflicts in packages/server-v4/openapi.v4.yaml (the schema layout shifted but the region field changes apply cleanly to both BrowserbaseSessionCreateParams and BrowserbaseSessionCreateParamsOutput).

Authorship preserved via git commit --author.

---

Summary by cubic

Clarifies how to choose a Stagehand region via the client baseUrl and deprecates the request-level region for Browserbase sessions. OpenAPI now lists regional endpoints so generated SDKs and docs reflect endpoint-based routing.

• New Features

  • SDK docs (Go, Java, Python, Ruby) now show option.WithBaseURL(), baseUrl, and base_url examples for regional endpoints.
  • OpenAPI servers include us-west-2 (default), us-east-1, eu-central-1, and ap-southeast-1 endpoints.

• Migration

  • Use the client baseUrl to pick a region; stop relying on request region (deprecated and ignored on hosted Stagehand).
  • Endpoints: https://api.stagehand.browserbase.com (us-west-2), https://api.use1.stagehand.browserbase.com (us-east-1), https://api.euc1.stagehand.browserbase.com (eu-central-1), https://api.apse1.stagehand.browserbase.com (ap-southeast-1).

^{Written for commit 3cb8fd4. Summary will update on new commits. Review in cubic}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3cb8fd4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

No issues found across 10 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant SDK as Generated SDK Client
    participant OpenAPI as OpenAPI Spec
    participant Server as Stagehand API Server
    participant Browserbase as Browserbase Session

    Note over Dev,Browserbase: Client Configuration Flow

    Dev->>SDK: Initialize client with region-specific baseUrl
    alt Go SDK
        Dev->>SDK: stagehand.NewClient(option.WithBaseURL("https://api.euc1..."))
    else Java SDK
        Dev->>SDK: StagehandOkHttpClient.builder().baseUrl("https://api.euc1...")
    else Python SDK
        Dev->>SDK: AsyncStagehand(base_url="https://api.euc1...")
    else Ruby SDK
        Dev->>SDK: Stagehand::Client.new(base_url: "https://api.euc1...")
    end

    Note over OpenAPI,SDK: OpenAPI servers list regional endpoints
    OpenAPI->>SDK: Provide regional baseUrl options
    SDK-->>Dev: Client configured for selected region

    Note over Dev,Browserbase: Runtime Session Creation

    Dev->>SDK: Create session (optionally with deprecated region field)
    SDK->>Server: POST /v1/session to configured baseUrl
    alt If region field provided in request
        Server->>Server: Override: use AWS_REGION from deployment instead
    end
    Server->>Browserbase: Create browser session in region matching baseUrl
    Browserbase-->>Server: Session created
    Server-->>SDK: Session response
    SDK-->>Dev: Session ready

    Note over OpenAPI,Server: Region Selection Behavior

    alt Client uses us-west-2 default (https://api.stagehand.browserbase.com)
        Server->>Browserbase: Launch in us-west-2
    else Client chooses us-east-1 (https://api.use1.stagehand.browserbase.com)
        Server->>Browserbase: Launch in us-east-1
    else Client chooses eu-central-1 (https://api.euc1.stagehand.browserbase.com)
        Server->>Browserbase: Launch in eu-central-1
    else Client chooses ap-southeast-1 (https://api.apse1.stagehand.browserbase.com)
        Server->>Browserbase: Launch in ap-southeast-1
    end

Loading

_{Re-trigger cubic}