> ## Documentation Index
> Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to Python SDK 1.0

> Adopt typed request dictionaries while keeping existing Pydantic request code working

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

```bash theme={null}
pip install --upgrade "hyperbrowser>=1.0,<2"
```

## Before and after

New and updated code should pass a dictionary:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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.

<Tip>
  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.
</Tip>

## JSON Schema and open mappings

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

```python theme={null}
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

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

No response-model migration is required.