[Claimed #1923] feat: Make model api key optional on API

[github-actions]

Mirrored from external contributor PR #1923 after approval by @miguelg719.

Original author: @chromiebot
Original PR: #1923
Approved source head SHA: 49c1be2be843d441e3234f6ab591e2ce5bd84087

@chromiebot, please continue any follow-up discussion on this mirrored PR. When the external PR gets new commits, this same internal PR will be marked stale until the latest external commit is approved and refreshed here.

Original description

why

Introducing Model Gateway on Browserbase

what changed

modelApiKey is now optional on API

test plan

---

Summary by cubic

Make the model API key optional in StagehandAPIClient.init() so sessions can start without a key, supporting Model Gateway. When provided, behavior is unchanged and the x-model-api-key header is sent.

• Bug Fixes
  • Remove throw in init(); make modelApiKey optional across types.
  • Conditionally send x-model-api-key; omit model apiKey in prepareModelConfig when undefined.
  • Add unit tests for header behavior and a server integration test for starting without the header; add a patch changeset for @browserbasehq/stagehand.

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

[github-actions]

This mirrored PR has been merged into main. The original external PR #1923 is now completed.

[changeset-bot]

🦋 Changeset detected

Latest commit: 7170d9e

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	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	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

[cubic-dev-ai]

1 issue found across 2 files

Confidence score: 3/5

• There is a meaningful regression risk: packages/core/lib/v3/api.ts appears to include Stagehand REST API client/server breaking changes without the required integration coverage under packages/server/test (severity 7/10, confidence 9/10).
• This is likely user-impacting if behavior diverges between client and server, so the PR is not a low-risk merge until integration tests validate the contract change.
• Pay close attention to packages/core/lib/v3/api.ts and packages/server/test - API contract changes need integration tests to catch breakage across client/server boundaries.

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/core/lib/v3/api.ts">

<violation number="1" location="packages/core/lib/v3/api.ts:108">
P1: Custom agent: **Any breaking changes to Stagehand REST API client / server implementation must be covered by an integration test under packages/server/test**

Rule d1dcea1f-c2ef-4728-9dd1-a92623cd374f is violated: this REST API client behavior change (optional `modelApiKey` / conditional `x-model-api-key`) is not covered by a server integration test for session start without a model key.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as Client Application
    participant SDK as StagehandAPIClient
    participant API as Stagehand API Server

    User->>SDK: init(params)
    
    Note over SDK: CHANGED: No longer throws if<br/>modelApiKey is missing
    
    SDK->>SDK: prepareModelConfig(model)
    alt apiKey provided in params or instance
        SDK->>SDK: Set apiKey in model configuration
    else apiKey omitted
        SDK->>SDK: NEW: Return model configuration<br/>without apiKey field
    end

    SDK->>SDK: Construct Headers
    opt modelApiKey is present
        Note over SDK: Set x-model-api-key header
    end

    SDK->>API: POST /session/start (fetch)
    Note over SDK,API: Headers: x-api-key, x-bb-session-id, ...
    
    alt modelApiKey provided
        Note over SDK,API: CHANGED: Includes x-model-api-key
    else modelApiKey omitted
        Note over SDK,API: NEW: Excludes x-model-api-key
    end

    API-->>SDK: SessionStartResult (200 OK)
    SDK-->>User: Initialized Instance

Loading

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