release: 3.20.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.19.5"
+  ".": "3.20.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 8
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-b969ce378479c79ee64c05127c0ed6c6ce2edbee017ecd037242fb618a5ebc9f.yml
-openapi_spec_hash: a24aabaa5214effb679808b7f2be0ad4
-config_hash: 0cc516caf1432087f40654336e0fa8cd
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase/stagehand-dbbff1a35360850898f7d60588e257faeac145a73cfcae634cfeb1b70109b6af.yml
+openapi_spec_hash: 28c4b734a5309067c39bb4c4b709b9ab
+config_hash: a962ae71493deb11a1c903256fb25386

CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 3.20.0 (2026-05-01)
+
+Full Changelog: [v3.19.5...v3.20.0](https://github.com/browserbase/stagehand-python/compare/v3.19.5...v3.20.0)
+
+### Features
+
+* [STG-1798] feat: support Browserbase verified sessions ([078ab5c](https://github.com/browserbase/stagehand-python/commit/078ab5c76f13beee16e44d7eed5e3018f1cc5bd8))
+* Bedrock auth passthrough ([9463fa4](https://github.com/browserbase/stagehand-python/commit/9463fa49cb839abbb2c6a1adb0d053e5006216a7))
+* Revert "[STG-1573] Add providerOptions for extensible model auth ([#1822](https://github.com/browserbase/stagehand-python/issues/1822))" ([3c04086](https://github.com/browserbase/stagehand-python/commit/3c0408675154c9f7d241c4e92e9cb82f0419d6b3))
+* support setting headers via env ([b1c6127](https://github.com/browserbase/stagehand-python/commit/b1c61276ff9cecf89c078e1d97a6b927d8d308e1))
+
+
+### Bug Fixes
+
+* **client:** preserve hardcoded query params when merging with user params ([feac39d](https://github.com/browserbase/stagehand-python/commit/feac39d88a841ff710d672b622f3280037589f66))
+* ensure file data are only sent as 1 parameter ([b870657](https://github.com/browserbase/stagehand-python/commit/b8706575ab0f95b9e6781ee3685f9b79e0fe6036))
+* use correct field name format for multipart file arrays ([852600a](https://github.com/browserbase/stagehand-python/commit/852600a4c6169df6497fc4d77a06abae8812e375))
+
+
+### Performance Improvements
+
+* **client:** optimize file structure copying in multipart requests ([69d396f](https://github.com/browserbase/stagehand-python/commit/69d396fa404d0ad3905786dcf6f56be8be7ab9b2))
+
+
+### Chores
+
+* **internal:** more robust bootstrap script ([9bc61e1](https://github.com/browserbase/stagehand-python/commit/9bc61e12f1599b14dd8b2a0c38a50c089512e9c7))
+
 ## 3.19.5 (2026-04-03)
 
 Full Changelog: [v3.19.4...v3.19.5](https://github.com/browserbase/stagehand-python/compare/v3.19.4...v3.19.5)

README.md

@@ -257,7 +257,7 @@ See this table for the available options:
 | `browserbase_api_key`    | `BROWSERBASE_API_KEY`    | true     | -                                         |
 | `browserbase_project_id` | `BROWSERBASE_PROJECT_ID` | true     | -                                         |
 | `model_api_key`          | `MODEL_API_KEY`          | true     | -                                         |
-| `base_url`               | `STAGEHAND_BASE_URL`     | false    | `"https://api.stagehand.browserbase.com"` |
+| `base_url`               | `STAGEHAND_API_URL`     | false    | `"https://api.stagehand.browserbase.com"` |
 
 Keyword arguments take precedence over environment variables.
 
@@ -662,7 +662,7 @@ import httpx
 from stagehand import Stagehand, DefaultHttpxClient
 
 client = Stagehand(
-    # Or use the `STAGEHAND_BASE_URL` env var
+    # Or use the `STAGEHAND_API_URL` env var
     base_url="http://my.test.server.example.com:8083",
     http_client=DefaultHttpxClient(
         proxy="http://my.test.proxy.example.com",

examples/env.py

@@ -44,9 +44,6 @@ def load_example_env() -> None:
             + " (from examples/.env)"
         )
 
-    # Normalize for SDKs that expect STAGEHAND_BASE_URL
-    os.environ.setdefault("STAGEHAND_BASE_URL", os.environ["STAGEHAND_API_URL"])
-
     # Use the repo-local SEA binary when available (avoid global installs).
     sea_binary = env_path.parent.parent / "bin" / "sea" / "stagehand-darwin-arm64"
     if sea_binary.exists():

examples/local_browser_playwright_example.py

@@ -15,7 +15,7 @@
 - BROWSERBASE_PROJECT_ID (can be any value in local mode)
 
 Optional:
-- STAGEHAND_BASE_URL (defaults to http://127.0.0.1:3000)
+- STAGEHAND_API_URL (defaults to http://127.0.0.1:3000)
 """
 
 from __future__ import annotations

examples/local_server_multiregion_browser_example.py

@@ -14,7 +14,7 @@
 - BROWSERBASE_PROJECT_ID
 
 Optional:
-- STAGEHAND_BASE_URL (defaults to http://127.0.0.1:3000 when server="local")
+- STAGEHAND_API_URL (defaults to http://127.0.0.1:3000 when server="local")
 """
 
 from __future__ import annotations

examples/playwright_page_example.py

@@ -13,7 +13,7 @@
 - BROWSERBASE_PROJECT_ID
 
 Optional:
-- STAGEHAND_BASE_URL (defaults to https://api.stagehand.browserbase.com)
+- STAGEHAND_API_URL (defaults to https://api.stagehand.browserbase.com)
 """
 
 from __future__ import annotations

examples/pydoll_tab_example.py

@@ -15,7 +15,7 @@
 - BROWSERBASE_PROJECT_ID
 
 Optional:
-- STAGEHAND_BASE_URL (defaults to https://api.stagehand.browserbase.com)
+- STAGEHAND_API_URL (defaults to https://api.stagehand.browserbase.com)
 
 Notes:
 - This example requires Python 3.10+ because `pydoll-python` requires Python 3.10+.

examples/remote_browser_playwright_example.py

@@ -15,7 +15,7 @@
 - BROWSERBASE_PROJECT_ID
 
 Optional:
-- STAGEHAND_BASE_URL (defaults to https://api.stagehand.browserbase.com)
+- STAGEHAND_API_URL (defaults to https://api.stagehand.browserbase.com)
 """
 
 from __future__ import annotations

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stagehand"
-version = "3.19.5"
+version = "3.20.0"
 description = "The official Python library for the stagehand API"
 dynamic = ["readme"]
 license = "MIT"

scripts/bootstrap

@@ -4,7 +4,7 @@ set -e
 
 cd "$(dirname "$0")/.."
 
-if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "$SKIP_BREW" != "1" ] && [ -t 0 ]; then
+if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "${SKIP_BREW:-}" != "1" ] && [ -t 0 ]; then
   brew bundle check >/dev/null 2>&1 || {
     echo -n "==> Install Homebrew dependencies? (y/N): "
     read -r response

src/stagehand/_base_client.py

@@ -540,6 +540,10 @@ def _build_request(
                 files = cast(HttpxRequestFiles, ForceMultipartDict())
 
         prepared_url = self._prepare_url(options.url)
+        # preserve hard-coded query params from the url
+        if params and prepared_url.query:
+            params = {**dict(prepared_url.params.items()), **params}
+            prepared_url = prepared_url.copy_with(raw_path=prepared_url.raw_path.split(b"?", 1)[0])
         if "_" in prepared_url.host:
             # work around https://github.com/encode/httpx/discussions/2880
             kwargs["extensions"] = {"sni_hostname": prepared_url.host.replace("_", "-")}

src/stagehand/_client.py

@@ -22,7 +22,11 @@
     RequestOptions,
     not_given,
 )
-from ._utils import is_given, get_async_library
+from ._utils import (
+    is_given,
+    is_mapping_t,
+    get_async_library,
+)
 from ._compat import cached_property
 from ._models import FinalRequestOptions
 from ._version import __version__
@@ -161,6 +165,15 @@ def __init__(
         )
     ### </END CUSTOM CODE>
 
+        custom_headers_env = os.environ.get("STAGEHAND_CUSTOM_HEADERS")
+        if custom_headers_env is not None:
+            parsed: dict[str, str] = {}
+            for line in custom_headers_env.split("\n"):
+                colon = line.find(":")
+                if colon >= 0:
+                    parsed[line[:colon].strip()] = line[colon + 1 :].strip()
+            default_headers = {**parsed, **(default_headers if is_mapping_t(default_headers) else {})}
+
         super().__init__(
             version=__version__,
             base_url=base_url,
@@ -447,6 +460,15 @@ def __init__(
         )
     ### </END CUSTOM CODE>
 
+        custom_headers_env = os.environ.get("STAGEHAND_CUSTOM_HEADERS")
+        if custom_headers_env is not None:
+            parsed: dict[str, str] = {}
+            for line in custom_headers_env.split("\n"):
+                colon = line.find(":")
+                if colon >= 0:
+                    parsed[line[:colon].strip()] = line[colon + 1 :].strip()
+            default_headers = {**parsed, **(default_headers if is_mapping_t(default_headers) else {})}
+
         super().__init__(
             version=__version__,
             base_url=base_url,

src/stagehand/_custom/sea_server.py

@@ -329,7 +329,7 @@ def configure_client_base_url(
         return base_url
 
     if base_url is None:
-        base_url = os.environ.get("STAGEHAND_BASE_URL")
+        base_url = os.environ.get("STAGEHAND_API_URL") or os.environ.get("STAGEHAND_BASE_URL")
     if base_url is None:
         base_url = "https://api.stagehand.browserbase.com"
     return base_url

src/stagehand/_files.py

@@ -3,8 +3,8 @@
 import io
 import os
 import pathlib
-from typing import overload
-from typing_extensions import TypeGuard
+from typing import Sequence, cast, overload
+from typing_extensions import TypeVar, TypeGuard
 
 import anyio
 
@@ -17,7 +17,9 @@
     HttpxFileContent,
     HttpxRequestFiles,
 )
-from ._utils import is_tuple_t, is_mapping_t, is_sequence_t
+from ._utils import is_list, is_mapping, is_tuple_t, is_mapping_t, is_sequence_t
+
+_T = TypeVar("_T")
 
 
 def is_base64_file_input(obj: object) -> TypeGuard[Base64FileInput]:
@@ -121,3 +123,51 @@ async def async_read_file_content(file: FileContent) -> HttpxFileContent:
         return await anyio.Path(file).read_bytes()
 
     return file
+
+
+def deepcopy_with_paths(item: _T, paths: Sequence[Sequence[str]]) -> _T:
+    """Copy only the containers along the given paths.
+
+    Used to guard against mutation by extract_files without copying the entire structure.
+    Only dicts and lists that lie on a path are copied; everything else
+    is returned by reference.
+
+    For example, given paths=[["foo", "files", "file"]] and the structure:
+        {
+            "foo": {
+                "bar": {"baz": {}},
+                "files": {"file": <content>}
+            }
+        }
+    The root dict, "foo", and "files" are copied (they lie on the path).
+    "bar" and "baz" are returned by reference (off the path).
+    """
+    return _deepcopy_with_paths(item, paths, 0)
+
+
+def _deepcopy_with_paths(item: _T, paths: Sequence[Sequence[str]], index: int) -> _T:
+    if not paths:
+        return item
+    if is_mapping(item):
+        key_to_paths: dict[str, list[Sequence[str]]] = {}
+        for path in paths:
+            if index < len(path):
+                key_to_paths.setdefault(path[index], []).append(path)
+
+        # if no path continues through this mapping, it won't be mutated and copying it is redundant
+        if not key_to_paths:
+            return item
+
+        result = dict(item)
+        for key, subpaths in key_to_paths.items():
+            if key in result:
+                result[key] = _deepcopy_with_paths(result[key], subpaths, index + 1)
+        return cast(_T, result)
+    if is_list(item):
+        array_paths = [path for path in paths if index < len(path) and path[index] == "<array>"]
+
+        # if no path expects a list here, nothing will be mutated inside it - return by reference
+        if not array_paths:
+            return cast(_T, item)
+        return cast(_T, [_deepcopy_with_paths(entry, array_paths, index + 1) for entry in item])
+    return item

src/stagehand/_qs.py

@@ -2,17 +2,13 @@
 
 from typing import Any, List, Tuple, Union, Mapping, TypeVar
 from urllib.parse import parse_qs, urlencode
-from typing_extensions import Literal, get_args
+from typing_extensions import get_args
 
-from ._types import NotGiven, not_given
+from ._types import NotGiven, ArrayFormat, NestedFormat, not_given
 from ._utils import flatten
 
 _T = TypeVar("_T")
 
-
-ArrayFormat = Literal["comma", "repeat", "indices", "brackets"]
-NestedFormat = Literal["dots", "brackets"]
-
 PrimitiveData = Union[str, int, float, bool, None]
 # this should be Data = Union[PrimitiveData, "List[Data]", "Tuple[Data]", "Mapping[str, Data]"]
 # https://github.com/microsoft/pyright/issues/3555

src/stagehand/_types.py

@@ -47,6 +47,9 @@
 ModelT = TypeVar("ModelT", bound=pydantic.BaseModel)
 _T = TypeVar("_T")
 
+ArrayFormat = Literal["comma", "repeat", "indices", "brackets"]
+NestedFormat = Literal["dots", "brackets"]
+
 
 # Approximates httpx internal ProxiesTypes and RequestFiles types
 # while adding support for `PathLike` instances

src/stagehand/_utils/__init__.py

@@ -24,7 +24,6 @@
     coerce_integer as coerce_integer,
     file_from_path as file_from_path,
     strip_not_given as strip_not_given,
-    deepcopy_minimal as deepcopy_minimal,
     get_async_library as get_async_library,
     maybe_coerce_float as maybe_coerce_float,
     get_required_header as get_required_header,