STG-1443 Add section in docs for baseUrl

[monadoid]

What

Add clearer documentation for using baseUrl / base_url to select a regional Stagehand API endpoint in generated SDK docs. Also mark browserbaseSessionCreateParams.region as deprecated in the generated spec/docs.

Note that our bugbots are complaining about not using zod meta for deprecated field but they are inaccurate - I tried this.

Why

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

Testing

• validated local Mintlify preview against the local v3 OpenAPI spec

[changeset-bot]

⚠️ No Changeset found

Latest commit: 44652a2

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]

✱ Stainless preview builds

This PR will update the stagehand SDKs with the following commit message.

feat: STG-1443 Customize regional baseUrl docs for generated SDKs

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ stagehand-typescript studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/stagehand-typescript/77b3b83a68a3410bc56823b71ba19b8a7da20a73/dist.tar.gz

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: This schema has been marked deprecated with `deprecated: true`, but no deprecation message has been supplied by `x-stainless-deprecation-message`.

✅ stagehand-openapi studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: This schema has been marked deprecated with `deprecated: true`, but no deprecation message has been supplied by `x-stainless-deprecation-message`.

✅ stagehand-php studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → lint ✅ → test ✅

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: This schema has been marked deprecated with `deprecated: true`, but no deprecation message has been supplied by `x-stainless-deprecation-message`.

✅ stagehand-kotlin studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: This schema has been marked deprecated with `deprecated: true`, but no deprecation message has been supplied by `x-stainless-deprecation-message`.

✅ stagehand-java studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

Add the following URL as a Maven source: 'https://pkg.stainless.com/s/stagehand-java/adf018ca3db223fd2957feb34961965aff0dcb60/mvn'

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: This schema has been marked deprecated with `deprecated: true`, but no deprecation message has been supplied by `x-stainless-deprecation-message`.

✅ stagehand-csharp studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ❗ → lint ❗ → test ✅

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: This schema has been marked deprecated with `deprecated: true`, but no deprecation message has been supplied by `x-stainless-deprecation-message`.

✅ stagehand-python studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

pip install https://pkg.stainless.com/s/stagehand-python/2e5b11961404a0112a3ce87ed0024e53b37b270e/stagehand-3.6.0-py3-none-any.whl

✅ stagehand-ruby studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: This schema has been marked deprecated with `deprecated: true`, but no deprecation message has been supplied by `x-stainless-deprecation-message`.

✅ stagehand-go studio · code · diff

Your SDK build had at least one "note" diagnostic, but this did not represent a regression.
generate ✅ → build ✅ → lint ✅ → test ✅

go get github.com/stainless-sdks/stagehand-go@7f928117e4979b6705b3e3059754dc03c60d85e6

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: This schema has been marked deprecated with `deprecated: true`, but no deprecation message has been supplied by `x-stainless-deprecation-message`.

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-03-13 22:48:26 UTC

[cubic-dev-ai]

3 issues found across 10 files

Confidence score: 4/5

• This PR is likely safe to merge, but there is a standards/completeness gap: region is described as deprecated without using the formal schema flag (deprecated: true), which reduces accuracy in generated API docs and client tooling.
• The most impactful issue is in packages/server-v4/openapi.v4.yaml (and matching output schema): without explicit deprecation metadata, consumers may not see deprecation warnings even though STG-1443 expects them.
• The same deprecation-marker mismatch appears in packages/server-v3/openapi.v3.yaml and packages/core/lib/v3/types/public/api.ts, so behavior is consistent but still not fully aligned with the requested spec contract.
• Pay close attention to packages/server-v4/openapi.v4.yaml, packages/server-v3/openapi.v3.yaml, and packages/core/lib/v3/types/public/api.ts - ensure region is formally marked with deprecated: true in request/output schemas and generated spec sources.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/server-v4/openapi.v4.yaml">

<violation number="1" location="packages/server-v4/openapi.v4.yaml:401">
P2: According to linked Linear issue STG-1443, this field needs a formal deprecation marker in the spec/docs. Add `deprecated: true` on this `region` property (and the matching output schema property), not just deprecation text in `description`.</violation>
</file>

<file name="packages/core/lib/v3/types/public/api.ts">

<violation number="1" location="packages/core/lib/v3/types/public/api.ts:292">
P2: According to linked Linear issue STG-1443, this field should be explicitly marked deprecated in the generated spec/docs; description text alone is not a schema deprecation flag.</violation>
</file>

<file name="packages/server-v3/openapi.v3.yaml">

<violation number="1" location="packages/server-v3/openapi.v3.yaml:401">
P2: According to linked Linear issue STG-1443, this field needs to be marked deprecated in generated spec/docs, but this change only adds descriptive text. Add `deprecated: true` for `region` (request and output schemas) so generators emit actual deprecation metadata.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client as SDK Client (Go/Py/Java/Ruby)
    participant API as Regional API Endpoint
    participant Server as Hosted Stagehand Server
    participant BB as Browserbase Infra

    Note over Client,API: User selects region via baseUrl (e.g., EU-Central-1)

    Client->>API: NEW: Request with baseUrl: 'https://api.euc1...'
    Note right of Client: Request may still contain<br/>deprecated 'region' field

    API->>Server: Route to regional instance
    
    Server->>Server: NEW: Resolve region from AWS_REGION env
    Note right of Server: CHANGED: Server overrides any<br/>provided 'region' parameter
    
    Server->>BB: Create session in resolved region
    BB-->>Server: Session metadata (ID, Region)
    
    Server-->>API: Session Details
    API-->>Client: 201 Created

    Note over Client,Server: 'browserbaseSessionCreateParams.region' is now deprecated

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/docs/v3/sdk/python.mdx">

<violation number="1" location="packages/docs/v3/sdk/python.mdx:245">
P2: According to linked Linear issue STG-1443, this section should explicitly mark `browserbaseSessionCreateParams.region` as deprecated; the new text only says it is retained for compatibility.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}