[STG-1808] Deprecate Browserbase project ID

[monadoid]

why

Browserbase API keys are project-scoped, so Stagehand should keep accepting project IDs without requiring them.

what changed

• Mark browserbaseSessionCreateParams.projectId deprecated in Zod/OpenAPI.
• Make BROWSERBASE_PROJECT_ID nullable/deprecated in Stainless config.
• Use Browserbase-returned projectId in the local server instead of x-bb-project-id.

projectId: z.string().optional().meta({ deprecated: true })

test plan

• pnpm --filter @browserbasehq/stagehand run lint
• pnpm --filter @browserbasehq/stagehand-server-v3 run lint

---

Summary by cubic

Deprecate Browserbase project ID per STG-1808; Stagehand now relies on project-scoped API keys and the project ID returned by Browserbase. The x-bb-project-id header, session projectId param, and BROWSERBASE_PROJECT_ID config are deprecated but remain optional for now.

• Refactors

  • Marked projectId in session create params as deprecated in Zod/OpenAPI; updated security scheme descriptions to reflect deprecation of x-bb-project-id.
  • Made BROWSERBASE_PROJECT_ID nullable and marked deprecated in stainless.yml.
  • Server now resolves projectId from the retrieved/created Browserbase session; stops reading x-bb-project-id and adjusts validation messages.

• Migration

  • Stop sending x-bb-project-id and remove BROWSERBASE_PROJECT_ID; they’re no longer needed.
  • Avoid passing projectId in session creation; it’s accepted but deprecated.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 870503e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v4	Patch

Not sure what this means? Click here to learn what changesets are.

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

[github-actions]

✱ Stainless preview builds

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

feat: [STG-1808] Deprecate Browserbase project ID

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

✅ stagehand-go studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ → lint ✅ → test ✅

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

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

✅ stagehand-php studio · conflict

Your SDK build had at least one new note diagnostic, which is a regression from the base state.

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

✅ stagehand-kotlin studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ✅

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

✅ stagehand-ruby studio · conflict

Your SDK build had at least one new note diagnostic, which is a regression from the base state.

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

✅ stagehand-typescript studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ✅ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ✅

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

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

⚡ stagehand-python studio · conflict

Your SDK build resulted in a merge conflict between your custom code and the newly generated changes, which is a regression from the base state.
You don't need to resolve this conflict right now, but you will need to resolve it for your changes to be released to your users. Read more about why this happened here.

✅ stagehand-java studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅ → build ✅ (prev: build ⏭️) → lint ✅ (prev: lint ⏭️) → test ✅

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

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

⚠️ stagehand-csharp studio · code · diff

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ (prev: build ⏭️) → lint ❗ (prev: lint ⏭️) → test ✅

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

✅ stagehand-openapi studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅

New diagnostics (1 note)

💡 Schema/DeprecatedWithoutMessage: Confirm schema is deprecated and add missing deprecation details if needed.

---

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-05-04 17:38:41 UTC

[cubic-dev-ai]

No issues found across 6 files

Confidence score: 5/5

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

Architecture diagram

sequenceDiagram
    participant Client
    participant Server as Stagehand Server (v3)
    participant BB as Browserbase API

    Note over Client,BB: Session Initialization Flow

    Client->>Server: POST /v1/sessions/start
    Note right of Client: Header: x-bb-api-key<br/>Optional: x-bb-project-id (DEPRECATED)

    alt Session ID provided
        Server->>BB: GET /sessions/{id}
        BB-->>Server: Return Session Object (id, projectId, connectUrl)
        Server->>Server: CHANGED: Extract projectId from BB response
    else New Session
        Server->>Server: Prepare Create Payload
        Note right of Server: DEPRECATED: projectId from params/headers<br/>no longer prioritized
        Server->>BB: POST /sessions (create)
        BB-->>Server: Return Session Object (id, projectId, connectUrl)
        Server->>Server: CHANGED: Extract projectId from BB response
    end

    alt Validation
        Server->>Server: Ensure browserbaseApiKey & resolved projectId exist
    else Missing Credentials
        Server-->>Client: 400 Bad Request
    end

    Note over Server: Initialize streaming context with<br/>resolved browserbaseProjectId

    Server-->>Client: 201 Created (Session Details)

    Note over Client,BB: Streaming / Command Execution

    Client->>Server: POST /v1/requests (stream)
    Server->>Server: CHANGED: Use resolved projectId (not from headers)
    Server->>BB: Connect to session via connectUrl
    BB-->>Server: WebSocket / Stream data
    Server-->>Client: Response Stream

Loading