[STG-2014] fix: mark project id optional in docs

[shrey150]

Summary

• mark deprecated Browserbase project ID as optional in generated API docs
• remove project ID from required v3 OpenAPI/Stainless auth requirements
• keep project ID available as an optional deprecated header value

Linear: https://linear.app/browserbase/issue/STG-2014/mark-project-id-optional-in-stagehand-api-docs

Verification

• pnpm --filter @browserbasehq/stagehand-server-v3 gen:openapi
• pnpm --filter @browserbasehq/stagehand-server-v3 typecheck
• pnpm -w exec prettier --check packages/server-v3/scripts/gen-openapi.ts stainless.yml .changeset/fix-stagehand-project-id-docs.md packages/server-v3/openapi.v3.yaml

---

Summary by cubic

Make Browserbase project ID optional in Stagehand v3 API docs and security. Removes it from required auth in OpenAPI/Stainless and keeps x-bb-project-id as a deprecated optional header. Aligns with Linear STG-2014.

• Migration
  • No action needed.
  • You can remove the x-bb-project-id header; it’s still accepted but deprecated.

^{Written for commit 32a13f1. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 32a13f1

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

This PR includes changesets to release 1 package

Name	Type
@browserbasehq/stagehand-server-v3	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 for stagehand

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

feat: [STG-2014] fix: mark project id optional in docs

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

⚡ stagehand-typescript 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-kotlin 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 · 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-go 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-php 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-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-csharp studio · code · diff

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

⚡ stagehand-ruby 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-openapi studio · code · diff

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

---

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-14 20:01:54 UTC

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

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

Architecture diagram

sequenceDiagram
    participant Client as SDK Client
    participant Stainless as Stainless Codegen
    participant Fastify as Fastify Server (v3)
    participant OpenAPI as OpenAPI Spec
    participant Docs as Generated API Docs

    Note over Client,Docs: Project ID Auth Flow (Deprecated Path)

    Client->>Stainless: Configure client (stainless.yml)
    alt x-bb-project-id provided
        Client->>Fastify: NEW: Send optional x-bb-project-id header
        Fastify->>Fastify: Accept deprecated header value
    end
    Note over Client,Fastify: Header is no longer required for authentication

    Stainless->>OpenAPI: Generate openapi.v3.yaml
    OpenAPI->>Fastify: Load security schemes
    Note over OpenAPI,Fastify: BBProjectIdAuth removed from required security list
    Fastify->>Fastify: Validate request against security schemes
    Note over Fastify: Only BrowserbaseApiKey is now required

    OpenAPI->>Docs: Generate API documentation
    Note over Docs: Project ID marked as deprecated optional header
    Docs->>Docs: Display x-bb-project-id as nullable, not required

    Note over Client,Docs: Happy Path (No Project ID)
    Client->>Stainless: Initialize without x-bb-project-id
    Stainless->>Fastify: Send API request (only x-bb-api-key)
    Fastify->>Fastify: Authenticate via BrowserbaseApiKey only
    Fastify-->>Client: 200 Success

    Note over Client,Docs: Deprecated Path (With Project ID)
    Client->>Stainless: Initialize with optional x-bb-project-id
    Stainless->>Fastify: Send request (x-bb-api-key + x-bb-project-id)
    Fastify->>Fastify: Authenticate via BrowserbaseApiKey
    Note over Fastify: x-bb-project-id accepted but ignored for auth
    Fastify-->>Client: 200 Success (backward compatible)

Loading