Migrating to Python SDK 1.0

Python SDK 1.0 makes plain dictionaries the preferred request format. Method signatures use TypedDict, so editors can autocomplete and validate top-level and nested keys directly in dictionary literals. Existing Pydantic request objects remain supported. You can upgrade first, then migrate call sites incrementally.

Upgrade

pip install --upgrade "hyperbrowser>=1.0,<2"

Before and after

New and updated code should pass a dictionary:

from hyperbrowser import Hyperbrowser

client = Hyperbrowser(api_key="your-api-key")
session = client.sessions.create(
    {
        "use_stealth": True,
        "screen": {"width": 1920, "height": 1080},
    }
)

The equivalent Pydantic request from earlier SDK versions remains valid:

from hyperbrowser.models import CreateSessionParams, ScreenConfig

session = client.sessions.create(
    CreateSessionParams(
        use_stealth=True,
        screen=ScreenConfig(width=1920, height=1080),
    )
)

Both forms can be used in the same application.

Named request annotations

Import request TypedDict definitions from hyperbrowser.types when a named variable is useful:

from hyperbrowser.types import CreateSessionParams

params: CreateSessionParams = {
    "use_stealth": True,
    "screen": {"width": 1920, "height": 1080},
}
session = client.sessions.create(params)

The same name under hyperbrowser.models refers to the legacy Pydantic request class. Alias one of the imports if you need both:

from hyperbrowser.models import CreateSessionParams as LegacyCreateSessionParams
from hyperbrowser.types import CreateSessionParams

What stays the same

Use Pythonic snake_case request keys. The SDK still translates its own fields to the API’s wire names.
Sync and async clients accept the same request shapes.
Responses remain Pydantic models with methods such as model_dump() and model_dump_json().
Legacy Pydantic requests retain their constructors and validation behavior.

If your application deliberately validates a request before making an SDK call, keep constructing the legacy class. Dictionaries are validated when the SDK method is called.

JSON Schema and open mappings

Fields such as schema and output_model_schema accept raw JSON Schema dictionaries:

result = client.extract.start_and_wait(
    {
        "urls": ["https://example.com"],
        "prompt": "Extract the product name and price.",
        "schema": {
            "type": "object",
            "properties": {
                "product_name": {"type": "string"},
                "price_in_usd": {"type": "number"},
            },
            "required": ["product_name", "price_in_usd"],
        },
    }
)

The SDK treats schema content as user-owned data. It does not rename $defs, $ref, property names such as product_name, or custom keywords. The same preservation rule applies to environment variables, storage state, sensitive data, and agent action payloads. Endpoints that support boolean JSON Schemas also accept True and False directly. Where documented, you can also provide a Pydantic model class and the SDK will generate its JSON Schema.

Migration checklist

Upgrade and run your current test suite. Existing Pydantic request objects should continue to work.
Prefer dictionaries in new and frequently edited request code.
Import named request annotations from hyperbrowser.types.
Continue importing responses and intentionally retained legacy request classes from hyperbrowser.models.
Run your type checker to catch invalid or misspelled nested keys.

No response-model migration is required.

​Upgrade

​Before and after

​Named request annotations

​What stays the same

​JSON Schema and open mappings

​Migration checklist

Upgrade

Before and after

Named request annotations

What stays the same

JSON Schema and open mappings

Migration checklist