smooth-py 0.2.8.dev20251009__py3-none-any.whl → 0.3.5.dev20251110__py3-none-any.whl

smooth/__init__.py

@@ -1,6 +1,8 @@
+# pyright: reportPrivateUsage=false
 """Smooth python SDK."""
 
 import asyncio
+import base64
 import io
 import logging
 import os
@@ -8,7 +10,7 @@ import time
 import urllib.parse
 import warnings
 from pathlib import Path
-from typing import Any, Literal, Type
+from typing import Any, Literal, NotRequired, Type, TypedDict
 
 import httpx
 import requests
@@ -26,932 +28,1494 @@ BASE_URL = "https://api.smooth.sh/api/"
 
 
 def _encode_url(url: str, interactive: bool = True, embed: bool = False) -> str:
-  parsed_url = urllib.parse.urlparse(url)
-  params = urllib.parse.parse_qs(parsed_url.query)
-  params.update({"interactive": "true" if interactive else "false", "embed": "true" if embed else "false"})
-  return urllib.parse.urlunparse(parsed_url._replace(query=urllib.parse.urlencode(params)))
+    parsed_url = urllib.parse.urlparse(url)
+    params = urllib.parse.parse_qs(parsed_url.query)
+    params.update(
+        {
+            "interactive": "true" if interactive else "false",
+            "embed": "true" if embed else "false",
+        }
+    )
+    return urllib.parse.urlunparse(
+        parsed_url._replace(query=urllib.parse.urlencode(params))
+    )
 
 
 # --- Models ---
-# These models define the data structures for API requests and responses.
+
+
+class Certificate(TypedDict):
+    """Client certificate for accessing secure websites.
+
+    Attributes:
+        file: p12 file object to be uploaded (e.g., open("cert.p12", "rb")).
+        password: Password to decrypt the certificate file. Optional.
+    """
+
+    file: str | io.IOBase  # Required - base64 string or binary IO
+    password: NotRequired[str]  # Optional
+    filters: NotRequired[
+        list[str]
+    ]  # Optional - TODO: Reserved for future use to specify URL patterns where the certificate should be applied.
+
+
+def _process_certificates(
+    certificates: list[Certificate] | None,
+) -> list[dict[str, Any]] | None:
+    """Process certificates, converting binary IO to base64-encoded strings.
+
+    Args:
+        certificates: List of certificates with file field as string or binary IO.
+
+    Returns:
+        List of certificates with file field as base64-encoded string, or None if input is None.
+    """
+    if certificates is None:
+        return None
+
+    processed_certs: list[dict[str, Any]] = []
+    for cert in certificates:
+        processed_cert = dict(cert)  # Create a copy
+
+        file_content = processed_cert["file"]
+        if isinstance(file_content, io.IOBase):
+            # Read the binary content and encode to base64
+            binary_data = file_content.read()
+            processed_cert["file"] = base64.b64encode(binary_data).decode("utf-8")
+        elif not isinstance(file_content, str):
+            raise TypeError(
+                f"Certificate file must be a string or binary IO, got {type(file_content)}"
+            )
+
+        processed_certs.append(processed_cert)
+
+    return processed_certs
 
 
 class TaskResponse(BaseModel):
-  """Task response model."""
+    """Task response model."""
 
-  model_config = ConfigDict(extra="allow")
+    model_config = ConfigDict(extra="allow")
 
-  id: str = Field(description="The ID of the task.")
-  status: Literal["waiting", "running", "done", "failed", "cancelled"] = Field(description="The status of the task.")
-  output: Any | None = Field(default=None, description="The output of the task.")
-  credits_used: int | None = Field(default=None, description="The amount of credits used to perform the task.")
-  device: Literal["desktop", "mobile"] | None = Field(default=None, description="The device type used for the task.")
-  live_url: str | None = Field(default=None, description="The URL to view and interact with the task execution.")
-  recording_url: str | None = Field(default=None, description="The URL to view the task recording.")
+    id: str = Field(description="The ID of the task.")
+    status: Literal["waiting", "running", "done", "failed", "cancelled"] = Field(
+        description="The status of the task."
+    )
+    output: Any | None = Field(default=None, description="The output of the task.")
+    credits_used: int | None = Field(
+        default=None, description="The amount of credits used to perform the task."
+    )
+    device: Literal["desktop", "mobile"] | None = Field(
+        default=None, description="The device type used for the task."
+    )
+    live_url: str | None = Field(
+        default=None,
+        description="The URL to view and interact with the task execution.",
+    )
+    recording_url: str | None = Field(
+        default=None, description="The URL to view the task recording."
+    )
+    downloads_url: str | None = Field(
+        default=None,
+        description="The URL of the archive containing the downloaded files.",
+    )
+    created_at: int | None = Field(
+        default=None, description="The timestamp when the task was created."
+    )
 
 
 class TaskRequest(BaseModel):
-  """Run task request model."""
-
-  model_config = ConfigDict(extra="allow")
-
-  task: str = Field(description="The task to run.")
-  response_model: dict[str, Any] | None = Field(
-    default=None, description="If provided, the JSON schema describing the desired output structure. Default is None"
-  )
-  url: str | None = Field(
-    default=None,
-    description="The starting URL for the task. If not provided, the agent will infer it from the task.",
-  )
-  metadata: dict[str, str | int | float | bool] | None = Field(
-    default=None, description="A dictionary containing variables or parameters that will be passed to the agent."
-  )
-  files: list[str] | None = Field(default=None, description="A list of file ids to pass to the agent.")
-  agent: Literal["smooth", "smooth-lite"] = Field(default="smooth", description="The agent to use for the task.")
-  max_steps: int = Field(default=32, ge=2, le=128, description="Maximum number of steps the agent can take (min 2, max 128).")
-  device: Literal["desktop", "mobile"] = Field(default="mobile", description="Device type for the task. Default is mobile.")
-  allowed_urls: list[str] | None = Field(
-    default=None,
-    description=(
-      "List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*). If None, all URLs are allowed."
-    ),
-  )
-  enable_recording: bool = Field(default=True, description="Enable video recording of the task execution. Default is True")
-  profile_id: str | None = Field(
-    default=None,
-    description=("Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials."),
-  )
-  profile_read_only: bool = Field(
-    default=False, description="If true, the profile specified by `profile_id` will be loaded in read-only mode."
-  )
-  stealth_mode: bool = Field(default=False, description="Run the browser in stealth mode.")
-  proxy_server: str | None = Field(
-    default=None,
-    description=(
-      "Proxy server url to route browser traffic through. Must include the protocol to use (e.g. http:// or https://)"
-    ),
-  )
-  proxy_username: str | None = Field(default=None, description="Proxy server username.")
-  proxy_password: str | None = Field(default=None, description="Proxy server password.")
-  experimental_features: dict[str, Any] | None = Field(
-    default=None, description="Experimental features to enable for the task."
-  )
-
-  @model_validator(mode="before")
-  @classmethod
-  def _handle_deprecated_session_id(cls, data: Any) -> Any:
-    if isinstance(data, dict) and "session_id" in data and "profile_id" not in data:
-      warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
-      data["profile_id"] = data.pop("session_id")
-    return data
-
-  @computed_field(return_type=str | None)
-  @property
-  def session_id(self):
-    """(Deprecated) Returns the session ID."""
-    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
-    return self.profile_id
-
-  @session_id.setter
-  def session_id(self, value):
-    """(Deprecated) Sets the session ID."""
-    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
-    self.profile_id = value
-
-  def model_dump(self, **kwargs) -> dict[str, Any]:
-    """Dump model to dict, including deprecated session_id for retrocompatibility."""
-    data = super().model_dump(**kwargs)
-    # Add deprecated session_id field for retrocompatibility
-    if "profile_id" in data:
-      data["session_id"] = data["profile_id"]
-    return data
+    """Run task request model."""
 
+    model_config = ConfigDict(extra="allow")
 
-class BrowserSessionRequest(BaseModel):
-  """Request model for creating a browser session."""
-
-  profile_id: str | None = Field(
-    default=None, description=("The profile ID to use for the browser session. If None, a new profile will be created.")
-  )
-  live_view: bool | None = Field(default=True, description="Request a live URL to interact with the browser session.")
-
-  @model_validator(mode="before")
-  @classmethod
-  def _handle_deprecated_session_id(cls, data: Any) -> Any:
-    if isinstance(data, dict) and "session_id" in data and "profile_id" not in data:
-      warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
-      data["profile_id"] = data.pop("session_id")
-    return data
-
-  @computed_field(return_type=str | None)
-  @property
-  def session_id(self):
-    """(Deprecated) Returns the session ID."""
-    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
-    return self.profile_id
-
-  @session_id.setter
-  def session_id(self, value):
-    """(Deprecated) Sets the session ID."""
-    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
-    self.profile_id = value
-
-  def model_dump(self, **kwargs) -> dict[str, Any]:
-    """Dump model to dict, including deprecated session_id for retrocompatibility."""
-    data = super().model_dump(**kwargs)
-    # Add deprecated session_id field for retrocompatibility
-    if "profile_id" in data:
-      data["session_id"] = data["profile_id"]
-    return data
+    task: str = Field(description="The task to run.")
+    response_model: dict[str, Any] | None = Field(
+        default=None,
+        description="If provided, the JSON schema describing the desired output structure. Default is None",
+    )
+    url: str | None = Field(
+        default=None,
+        description="The starting URL for the task. If not provided, the agent will infer it from the task.",
+    )
+    metadata: dict[str, str | int | float | bool] | None = Field(
+        default=None,
+        description="A dictionary containing variables or parameters that will be passed to the agent.",
+    )
+    files: list[str] | None = Field(
+        default=None, description="A list of file ids to pass to the agent."
+    )
+    agent: Literal["smooth", "smooth-lite"] = Field(
+        default="smooth", description="The agent to use for the task."
+    )
+    max_steps: int = Field(
+        default=32,
+        ge=2,
+        le=128,
+        description="Maximum number of steps the agent can take (min 2, max 128).",
+    )
+    device: Literal["desktop", "mobile"] = Field(
+        default="desktop", description="Device type for the task. Default is desktop."
+    )
+    allowed_urls: list[str] | None = Field(
+        default=None,
+        description=(
+            "List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*). If None, all URLs are allowed."
+        ),
+    )
+    enable_recording: bool = Field(
+        default=True,
+        description="Enable video recording of the task execution. Default is True",
+    )
+    profile_id: str | None = Field(
+        default=None,
+        description=(
+            "Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials."
+        ),
+    )
+    profile_read_only: bool = Field(
+        default=False,
+        description=(
+            "If true, the profile specified by `profile_id` will be loaded in read-only mode. "
+            "Changes made during the task will not be saved back to the profile."
+        ),
+    )
+    stealth_mode: bool = Field(
+        default=False, description="Run the browser in stealth mode."
+    )
+    proxy_server: str | None = Field(
+        default=None,
+        description=(
+            "Proxy server url to route browser traffic through."
+        ),
+    )
+    proxy_username: str | None = Field(
+        default=None, description="Proxy server username."
+    )
+    proxy_password: str | None = Field(
+        default=None, description="Proxy server password."
+    )
+    certificates: list[dict[str, Any]] | None = Field(
+        default=None,
+        description=(
+            "List of client certificates to use when accessing secure websites. "
+            "Each certificate is a dictionary with the following fields:\n"
+            " - `file`: p12 file object to be uploaded (e.g., open('cert.p12', 'rb')).\n"
+            " - `password` (optional): Password to decrypt the certificate file."
+        ),
+    )
+    use_adblock: bool | None = Field(
+        default=True,
+        description="Enable adblock for the browser session. Default is True.",
+    )
+    additional_tools: dict[str, dict[str, Any] | None] | None = Field(
+        default=None, description="Additional tools to enable for the task."
+    )
+    experimental_features: dict[str, Any] | None = Field(
+        default=None, description="Experimental features to enable for the task."
+    )
+    extensions: list[str] | None = Field(
+        default=None, description="List of extensions to install for the task."
+    )
 
+    @model_validator(mode="before")
+    @classmethod
+    def _handle_deprecated_session_id(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "session_id" in data and "profile_id" not in data:
+            warnings.warn(
+                "'session_id' is deprecated, use 'profile_id' instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            data["profile_id"] = data.pop("session_id")
+        return data
+
+    @computed_field(return_type=str | None)
+    @property
+    def session_id(self):
+        """(Deprecated) Returns the session ID."""
+        warnings.warn(
+            "'session_id' is deprecated, use 'profile_id' instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.profile_id
+
+    @session_id.setter
+    def session_id(self, value: str | None):
+        """(Deprecated) Sets the session ID."""
+        warnings.warn(
+            "'session_id' is deprecated, use 'profile_id' instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.profile_id = value
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        """Dump model to dict, including deprecated session_id for retrocompatibility."""
+        data = super().model_dump(**kwargs)
+        # Add deprecated session_id field for retrocompatibility
+        if "profile_id" in data:
+            data["session_id"] = data["profile_id"]
+        return data
 
-class BrowserSessionResponse(BaseModel):
-  """Browser session response model."""
-
-  profile_id: str = Field(description="The ID of the browser profile associated with the opened browser instance.")
-  live_id: str | None = Field(description="The ID of the live browser session.")
-  live_url: str | None = Field(default=None, description="The live URL to interact with the browser session.")
-
-  @model_validator(mode="before")
-  @classmethod
-  def _handle_deprecated_session_id(cls, data: Any) -> Any:
-    if isinstance(data, dict) and "session_id" in data and "profile_id" not in data:
-      warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
-      data["profile_id"] = data.pop("session_id")
-    return data
-
-  @computed_field(return_type=str | None)
-  @property
-  def session_id(self):
-    """(Deprecated) Returns the session ID."""
-    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
-    return self.profile_id
-
-  @session_id.setter
-  def session_id(self, value):
-    """(Deprecated) Sets the session ID."""
-    warnings.warn("'session_id' is deprecated, use 'profile_id' instead", DeprecationWarning, stacklevel=2)
-    self.profile_id = value
 
+class BrowserSessionRequest(BaseModel):
+    """Request model for creating a browser session."""
 
-class BrowserProfilesResponse(BaseModel):
-  """Response model for listing browser profiles."""
-
-  profile_ids: list[str] = Field(description="The IDs of the browser profiles.")
-
-  @model_validator(mode="before")
-  @classmethod
-  def _handle_deprecated_session_ids(cls, data: Any) -> Any:
-    if isinstance(data, dict) and "session_ids" in data and "profile_ids" not in data:
-      warnings.warn("'session_ids' is deprecated, use 'profile_ids' instead", DeprecationWarning, stacklevel=2)
-      data["profile_ids"] = data.pop("session_ids")
-    return data
-
-  @computed_field(return_type=list[str])
-  @property
-  def session_ids(self):
-    """(Deprecated) Returns the session IDs."""
-    warnings.warn("'session_ids' is deprecated, use 'profile_ids' instead", DeprecationWarning, stacklevel=2)
-    return self.profile_ids
-
-  @session_ids.setter
-  def session_ids(self, value):
-    """(Deprecated) Sets the session IDs."""
-    warnings.warn("'session_ids' is deprecated, use 'profile_ids' instead", DeprecationWarning, stacklevel=2)
-    self.profile_ids = value
-
-  def model_dump(self, **kwargs) -> dict[str, Any]:
-    """Dump model to dict, including deprecated session_ids for retrocompatibility."""
-    data = super().model_dump(**kwargs)
-    # Add deprecated session_ids field for retrocompatibility
-    if "profile_ids" in data:
-      data["session_ids"] = data["profile_ids"]
-    return data
+    model_config = ConfigDict(extra="allow")
 
+    profile_id: str | None = Field(
+        default=None,
+        description=(
+            "The profile ID to use for the browser session. If None, a new profile will be created."
+        ),
+    )
+    live_view: bool | None = Field(
+        default=True,
+        description="Request a live URL to interact with the browser session.",
+    )
+    device: Literal["desktop", "mobile"] | None = Field(
+        default="desktop", description="The device type to use."
+    )
+    url: str | None = Field(
+        default=None, description="The URL to open in the browser session."
+    )
+    proxy_server: str | None = Field(
+        default=None,
+        description=(
+            "Proxy server address to route browser traffic through."
+        ),
+    )
+    proxy_username: str | None = Field(
+        default=None, description="Proxy server username."
+    )
+    proxy_password: str | None = Field(
+        default=None, description="Proxy server password."
+    )
 
-class BrowserSessionsResponse(BrowserProfilesResponse):
-  """Response model for listing browser profiles."""
+    @model_validator(mode="before")
+    @classmethod
+    def _handle_deprecated_session_id(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "session_id" in data and "profile_id" not in data:
+            warnings.warn(
+                "'session_id' is deprecated, use 'profile_id' instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            data["profile_id"] = data.pop("session_id")
+        return data
+
+    @computed_field(return_type=str | None)
+    @property
+    def session_id(self):
+        """(Deprecated) Returns the session ID."""
+        warnings.warn(
+            "'session_id' is deprecated, use 'profile_id' instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.profile_id
+
+    @session_id.setter
+    def session_id(self, value: str | None):
+        """(Deprecated) Sets the session ID."""
+        warnings.warn(
+            "'session_id' is deprecated, use 'profile_id' instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.profile_id = value
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        """Dump model to dict, including deprecated session_id for retrocompatibility."""
+        data = super().model_dump(**kwargs)
+        # Add deprecated session_id field for retrocompatibility
+        if "profile_id" in data:
+            data["session_id"] = data["profile_id"]
+        return data
 
-  pass
 
+class BrowserSessionResponse(BaseModel):
+    """Browser session response model."""
 
-class UploadFileResponse(BaseModel):
-  """Response model for uploading a file."""
+    model_config = ConfigDict(extra="allow")
 
-  id: str = Field(description="The ID assigned to the uploaded file.")
+    profile_id: str = Field(
+        description="The ID of the browser profile associated with the opened browser instance."
+    )
+    live_id: str | None = Field(default=None, description="The ID of the live browser session.")
+    live_url: str | None = Field(
+        default=None, description="The live URL to interact with the browser session."
+    )
 
+    @model_validator(mode="before")
+    @classmethod
+    def _handle_deprecated_session_id(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "session_id" in data and "profile_id" not in data:
+            warnings.warn(
+                "'session_id' is deprecated, use 'profile_id' instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            data["profile_id"] = data.pop("session_id")
+        return data
+
+    @computed_field(return_type=str | None)
+    @property
+    def session_id(self):
+        """(Deprecated) Returns the session ID."""
+        warnings.warn(
+            "'session_id' is deprecated, use 'profile_id' instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.profile_id
+
+    @session_id.setter
+    def session_id(self, value: str):
+        """(Deprecated) Sets the session ID."""
+        warnings.warn(
+            "'session_id' is deprecated, use 'profile_id' instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.profile_id = value
 
-# --- Exception Handling ---
 
+class BrowserProfilesResponse(BaseModel):
+    """Response model for listing browser profiles."""
+
+    model_config = ConfigDict(extra="allow")
+
+    profile_ids: list[str] = Field(description="The IDs of the browser profiles.")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _handle_deprecated_session_ids(cls, data: Any) -> Any:
+        if (
+            isinstance(data, dict)
+            and "session_ids" in data
+            and "profile_ids" not in data
+        ):
+            warnings.warn(
+                "'session_ids' is deprecated, use 'profile_ids' instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            data["profile_ids"] = data.pop("session_ids")
+        return data
+
+    @computed_field(return_type=list[str])
+    @property
+    def session_ids(self):
+        """(Deprecated) Returns the session IDs."""
+        warnings.warn(
+            "'session_ids' is deprecated, use 'profile_ids' instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.profile_ids
+
+    @session_ids.setter
+    def session_ids(self, value: list[str]):
+        """(Deprecated) Sets the session IDs."""
+        warnings.warn(
+            "'session_ids' is deprecated, use 'profile_ids' instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.profile_ids = value
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        """Dump model to dict, including deprecated session_ids for retrocompatibility."""
+        data = super().model_dump(**kwargs)
+        # Add deprecated session_ids field for retrocompatibility
+        if "profile_ids" in data:
+            data["session_ids"] = data["profile_ids"]
+        return data
 
-class ApiError(Exception):
-  """Custom exception for API errors."""
 
-  def __init__(self, status_code: int, detail: str, response_data: dict[str, Any] | None = None):
-    """Initializes the API error."""
-    self.status_code = status_code
-    self.detail = detail
-    self.response_data = response_data
-    super().__init__(f"API Error {status_code}: {detail}")
+class BrowserSessionsResponse(BrowserProfilesResponse):
+    """Response model for listing browser profiles."""
 
+    pass
 
-class TimeoutError(Exception):
-  """Custom exception for task timeouts."""
 
-  pass
+class UploadFileResponse(BaseModel):
+    """Response model for uploading a file."""
 
+    model_config = ConfigDict(extra="allow")
 
-# --- Base Client ---
+    id: str = Field(description="The ID assigned to the uploaded file.")
 
 
-class BaseClient:
-  """Base client for handling common API interactions."""
-
-  def __init__(self, api_key: str | None = None, base_url: str = BASE_URL, api_version: str = "v1"):
-    """Initializes the base client."""
-    # Try to get API key from environment if not provided
-    if not api_key:
-      api_key = os.getenv("CIRCLEMIND_API_KEY")
-
-    if not api_key:
-      raise ValueError("API key is required. Provide it directly or set CIRCLEMIND_API_KEY environment variable.")
-
-    if not base_url:
-      raise ValueError("Base URL cannot be empty.")
-
-    self.api_key = api_key
-    self.base_url = f"{base_url.rstrip('/')}/{api_version}"
-    self.headers = {
-      "apikey": self.api_key,
-      "User-Agent": "smooth-python-sdk/0.2.5",
-    }
-
-  def _handle_response(self, response: requests.Response | httpx.Response) -> dict[str, Any]:
-    """Handles HTTP responses and raises exceptions for errors."""
-    if 200 <= response.status_code < 300:
-      try:
-        return response.json()
-      except ValueError as e:
-        logger.error(f"Failed to parse JSON response: {e}")
-        raise ApiError(status_code=response.status_code, detail="Invalid JSON response from server") from None
-
-    # Handle error responses
-    error_data = None
-    try:
-      error_data = response.json()
-      detail = error_data.get("detail", response.text)
-    except ValueError:
-      detail = response.text or f"HTTP {response.status_code} error"
-
-    logger.error(f"API error: {response.status_code} - {detail}")
-    raise ApiError(status_code=response.status_code, detail=detail, response_data=error_data)
+class UploadExtensionResponse(BaseModel):
+    """Response model for uploading an extension."""
 
+    model_config = ConfigDict(extra="allow")
 
-# --- Synchronous Client ---
+    id: str = Field(description="The uploaded extension ID.")
 
 
-class BrowserSessionHandle(BaseModel):
-  """Browser session handle model."""
+class Extension(BaseModel):
+    """Extension model."""
 
-  browser_session: BrowserSessionResponse = Field(description="The browser session associated with this handle.")
+    model_config = ConfigDict(extra="allow")
 
-  @deprecated("session_id is deprecated, use profile_id instead")
-  def session_id(self):
-    """Returns the session ID for the browser session."""
-    return self.profile_id()
+    id: str = Field(description="The ID of the extension.")
+    file_name: str = Field(description="The name of the extension.")
+    creation_time: int = Field(description="The creation timestamp.")
 
-  def profile_id(self):
-    """Returns the profile ID for the browser session."""
-    return self.browser_session.profile_id
 
-  def live_url(self, interactive: bool = True, embed: bool = False):
-    """Returns the live URL for the browser session."""
-    if self.browser_session.live_url:
-      return _encode_url(self.browser_session.live_url, interactive=interactive, embed=embed)
-    return None
+class ListExtensionsResponse(BaseModel):
+    """Response model for listing extensions."""
 
+    model_config = ConfigDict(extra="allow")
 
-class TaskHandle:
-  """A handle to a running task."""
-
-  def __init__(self, task_id: str, client: "SmoothClient"):
-    """Initializes the task handle."""
-    self._client = client
-    self._task_response: TaskResponse | None = None
-
-    self._id = task_id
-
-  def id(self):
-    """Returns the task ID."""
-    return self._id
-
-  def stop(self):
-    """Stops the task."""
-    try:
-      response = self._client._client.delete(f"{self._client.base_url}/task/{self._id}")
-      self._handle_response(response)
-    except requests.exceptions.RequestException as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  def result(self, timeout: int | None = None, poll_interval: float = 1) -> TaskResponse:
-    """Waits for the task to complete and returns the result."""
-    if self._task_response and self._task_response.status not in ["running", "waiting"]:
-      return self._task_response
-
-    if timeout is not None and timeout < 1:
-      raise ValueError("Timeout must be at least 1 second.")
-    if poll_interval < 0.1:
-      raise ValueError("Poll interval must be at least 100 milliseconds.")
-
-    start_time = time.time()
-    while timeout is None or (time.time() - start_time) < timeout:
-      task_response = self._client._get_task(self.id())
-      self._task_response = task_response
-      if task_response.status not in ["running", "waiting"]:
-        return task_response
-      time.sleep(poll_interval)
-    raise TimeoutError(f"Task {self.id()} did not complete within {timeout} seconds.")
-
-  def live_url(self, interactive: bool = False, embed: bool = False, timeout: int | None = None):
-    """Returns the live URL for the task."""
-    if self._task_response and self._task_response.live_url:
-      return _encode_url(self._task_response.live_url, interactive=interactive, embed=embed)
-
-    start_time = time.time()
-    while timeout is None or (time.time() - start_time) < timeout:
-      task_response = self._client._get_task(self.id())
-      self._task_response = task_response
-      if self._task_response.live_url:
-        return _encode_url(self._task_response.live_url, interactive=interactive, embed=embed)
-      time.sleep(1)
-
-    raise TimeoutError(f"Live URL not available for task {self.id()}.")
-
-  def recording_url(self, timeout: int | None = None) -> str:
-    """Returns the recording URL for the task."""
-    if self._task_response and self._task_response.recording_url is not None:
-      return self._task_response.recording_url
-
-    start_time = time.time()
-    while timeout is None or (time.time() - start_time) < timeout:
-      task_response = self._client._get_task(self.id())
-      self._task_response = task_response
-      if task_response.recording_url is not None:
-        return task_response.recording_url
-      time.sleep(1)
-    raise TimeoutError(f"Recording URL not available for task {self.id()}.")
+    extensions: list[Extension] = Field(description="The list of extensions.")
 
 
-class SmoothClient(BaseClient):
-  """A synchronous client for the API."""
-
-  def __init__(self, api_key: str | None = None, base_url: str = BASE_URL, api_version: str = "v1"):
-    """Initializes the synchronous client."""
-    super().__init__(api_key, base_url, api_version)
-    self._session = requests.Session()
-    self._session.headers.update(self.headers)
-
-  def __enter__(self):
-    """Enters the synchronous context manager."""
-    return self
-
-  def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any):
-    """Exits the synchronous context manager."""
-    self.close()
-
-  def close(self):
-    """Close the session."""
-    if hasattr(self, "_session"):
-      self._session.close()
-
-  def _submit_task(self, payload: TaskRequest) -> TaskResponse:
-    """Submits a task to be run."""
-    try:
-      response = self._session.post(f"{self.base_url}/task", json=payload.model_dump(exclude_none=True))
-      data = self._handle_response(response)
-      return TaskResponse(**data["r"])
-    except requests.exceptions.RequestException as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  def _get_task(self, task_id: str) -> TaskResponse:
-    """Retrieves the status and result of a task."""
-    if not task_id:
-      raise ValueError("Task ID cannot be empty.")
-
-    try:
-      response = self._session.get(f"{self.base_url}/task/{task_id}")
-      data = self._handle_response(response)
-      return TaskResponse(**data["r"])
-    except requests.exceptions.RequestException as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  def run(
-    self,
-    task: str,
-    response_model: dict[str, Any] | Type[BaseModel] | None = None,
-    url: str | None = None,
-    metadata: dict[str, str | int | float | bool] | None = None,
-    files: list[str] | None = None,
-    agent: Literal["smooth"] = "smooth",
-    max_steps: int = 32,
-    device: Literal["desktop", "mobile"] = "mobile",
-    allowed_urls: list[str] | None = None,
-    enable_recording: bool = False,
-    session_id: str | None = None,
-    profile_id: str | None = None,
-    profile_read_only: bool = False,
-    stealth_mode: bool = False,
-    proxy_server: str | None = None,
-    proxy_username: str | None = None,
-    proxy_password: str | None = None,
-    experimental_features: dict[str, Any] | None = None,
-  ) -> TaskHandle:
-    """Runs a task and returns a handle to the task.
-
-    This method submits a task and returns a `TaskHandle` object
-    that can be used to get the result of the task.
+# --- Exception Handling ---
 
-    Args:
-        task: The task to run.
-        response_model: If provided, the schema describing the desired output structure.
-        url: The starting URL for the task. If not provided, the agent will infer it from the task.
-        metadata: A dictionary containing variables or parameters that will be passed to the agent.
-        files: A dictionary of file names to their ids. These files will be passed to the agent.
-        agent: The agent to use for the task.
-        max_steps: Maximum number of steps the agent can take (max 64).
-        device: Device type for the task. Default is mobile.
-        allowed_urls: List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*).
-          If None, all URLs are allowed.
-        enable_recording: Enable video recording of the task execution.
-        session_id: (Deprecated, now `profile_id`) Browser session ID to use.
-        profile_id: Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials.
-        profile_read_only: If true, the profile specified by `profile_id` will be loaded in read-only mode.
-        stealth_mode: Run the browser in stealth mode.
-        proxy_server: Proxy server url to route browser traffic through.
-        proxy_username: Proxy server username.
-        proxy_password: Proxy server password.
-        experimental_features: Experimental features to enable for the task.
 
-    Returns:
-        A handle to the running task.
+class ApiError(Exception):
+    """Custom exception for API errors."""
 
-    Raises:
-        ApiException: If the API request fails.
-    """
-    payload = TaskRequest(
-      task=task,
-      response_model=response_model.model_json_schema() if issubclass(response_model, BaseModel) else response_model,
-      url=url,
-      metadata=metadata,
-      files=files,
-      agent=agent,
-      max_steps=max_steps,
-      device=device,
-      allowed_urls=allowed_urls,
-      enable_recording=enable_recording,
-      profile_id=profile_id or session_id,
-      profile_read_only=profile_read_only,
-      stealth_mode=stealth_mode,
-      proxy_server=proxy_server,
-      proxy_username=proxy_username,
-      proxy_password=proxy_password,
-      experimental_features=experimental_features,
-    )
-    initial_response = self._submit_task(payload)
-
-    return TaskHandle(initial_response.id, self)
-
-  def open_session(
-    self, profile_id: str | None = None, session_id: str | None = None, live_view: bool = True
-  ) -> BrowserSessionHandle:
-    """Opens an interactive browser instance to interact with a specific browser profile.
+    def __init__(
+        self, status_code: int, detail: str, response_data: dict[str, Any] | None = None
+    ):
+        """Initializes the API error."""
+        self.status_code = status_code
+        self.detail = detail
+        self.response_data = response_data
+        super().__init__(f"API Error {status_code}: {detail}")
 
-    Args:
-        profile_id: The profile ID to use for the session. If None, a new profile will be created.
-        session_id: (Deprecated, now `profile_id`) The session ID to associate with the browser.
-        live_view: Whether to enable live view for the session.
 
-    Returns:
-        The browser session details, including the live URL.
+class TimeoutError(Exception):
+    """Custom exception for task timeouts."""
 
-    Raises:
-        ApiException: If the API request fails.
-    """
-    try:
-      response = self._session.post(
-        f"{self.base_url}/browser/session",
-        json=BrowserSessionRequest(profile_id=profile_id or session_id, live_view=live_view).model_dump(exclude_none=True),
-      )
-      data = self._handle_response(response)
-      return BrowserSessionHandle(browser_session=BrowserSessionResponse(**data["r"]))
-    except requests.exceptions.RequestException as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  def close_session(self, live_id: str):
-    """Closes a browser session."""
-    try:
-      response = self._session.delete(f"{self.base_url}/browser/session/{live_id}")
-      self._handle_response(response)
-    except requests.exceptions.RequestException as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  def list_profiles(self):
-    """Lists all browser profiles for the user.
+    pass
 
-    Returns:
-        A list of existing browser profiles.
 
-    Raises:
-        ApiException: If the API request fails.
-    """
-    try:
-      response = self._session.get(f"{self.base_url}/browser/session")
-      data = self._handle_response(response)
-      return BrowserProfilesResponse(**data["r"])
-    except requests.exceptions.RequestException as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  @deprecated("list_sessions is deprecated, use list_profiles instead")
-  def list_sessions(self):
-    """Lists all browser profiles for the user."""
-    return self.list_profiles()
-
-  def delete_profile(self, profile_id: str):
-    """Delete a browser profile."""
-    try:
-      response = self._session.delete(f"{self.base_url}/browser/session/{profile_id}")
-      self._handle_response(response)
-    except requests.exceptions.RequestException as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  @deprecated("delete_session is deprecated, use delete_profile instead")
-  def delete_session(self, session_id: str):
-    """Delete a browser profile."""
-    self.delete_profile(session_id)
-
-  def upload_file(self, file: io.IOBase, name: str | None = None, purpose: str | None = None) -> UploadFileResponse:
-    """Upload a file and return the file ID.
+# --- Base Client ---
 
-    Args:
-        file: File object to be uploaded.
-        name: Optional custom name for the file. If not provided, the original file name will be used.
-        purpose: Optional short description of the file to describe its purpose (i.e., 'the bank statement pdf').
 
-    Returns:
-        The file ID assigned to the uploaded file.
+class BaseClient:
+    """Base client for handling common API interactions."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = BASE_URL,
+        api_version: str = "v1",
+    ):
+        """Initializes the base client."""
+        # Try to get API key from environment if not provided
+        if not api_key:
+            api_key = os.getenv("CIRCLEMIND_API_KEY")
+
+        if not api_key:
+            raise ValueError(
+                "API key is required. Provide it directly or set CIRCLEMIND_API_KEY environment variable."
+            )
+
+        if not base_url:
+            raise ValueError("Base URL cannot be empty.")
+
+        self.api_key = api_key
+        self.base_url = f"{base_url.rstrip('/')}/{api_version}"
+        self.headers = {
+            "apikey": self.api_key,
+            "User-Agent": "smooth-python-sdk/0.2.5",
+        }
+
+    def _handle_response(
+        self, response: requests.Response | httpx.Response
+    ) -> dict[str, Any]:
+        """Handles HTTP responses and raises exceptions for errors."""
+        if 200 <= response.status_code < 300:
+            try:
+                return response.json()
+            except ValueError as e:
+                logger.error(f"Failed to parse JSON response: {e}")
+                raise ApiError(
+                    status_code=response.status_code,
+                    detail="Invalid JSON response from server",
+                ) from None
+
+        # Handle error responses
+        error_data = None
+        try:
+            error_data = response.json()
+            detail = error_data.get("detail", response.text)
+        except ValueError:
+            detail = response.text or f"HTTP {response.status_code} error"
+
+        logger.error(f"API error: {response.status_code} - {detail}")
+        raise ApiError(
+            status_code=response.status_code, detail=detail, response_data=error_data
+        )
 
-    Raises:
-        ValueError: If the file doesn't exist or can't be read.
-        ApiError: If the API request fails.
-    """
-    try:
-      name = name or getattr(file, "name", None)
-      if name is None:
-        raise ValueError("File name must be provided or the file object must have a 'name' attribute.")
-
-      if purpose:
-        data = {"file_purpose": purpose}
-      else:
-        data = None
-
-      files = {"file": (Path(name).name, file)}
-      response = self._session.post(f"{self.base_url}/file", files=files, data=data)
-      data = self._handle_response(response)
-      return UploadFileResponse(**data["r"])
-    except requests.exceptions.RequestException as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  def delete_file(self, file_id: str):
-    """Delete a file by its ID."""
-    try:
-      response = self._session.delete(f"{self.base_url}/file/{file_id}")
-      self._handle_response(response)
-    except requests.exceptions.RequestException as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
+# --- Synchronous Client ---
 
-# --- Asynchronous Client ---
 
+class BrowserSessionHandle(BaseModel):
+    """Browser session handle model."""
 
-class AsyncTaskHandle:
-  """An asynchronous handle to a running task."""
-
-  def __init__(self, task_id: str, client: "SmoothAsyncClient"):
-    """Initializes the asynchronous task handle."""
-    self._client = client
-    self._task_response: TaskResponse | None = None
-
-    self._id = task_id
-
-  def id(self):
-    """Returns the task ID."""
-    return self._id
-
-  async def result(self, timeout: int | None = None, poll_interval: float = 1) -> TaskResponse:
-    """Waits for the task to complete and returns the result."""
-    if self._task_response and self._task_response.status not in ["running", "waiting"]:
-      return self._task_response
-
-    if timeout is not None and timeout < 1:
-      raise ValueError("Timeout must be at least 1 second.")
-    if poll_interval < 0.1:
-      raise ValueError("Poll interval must be at least 100 milliseconds.")
-
-    start_time = time.time()
-    while timeout is None or (time.time() - start_time) < timeout:
-      task_response = await self._client._get_task(self.id())
-      self._task_response = task_response
-      if task_response.status not in ["running", "waiting"]:
-        return task_response
-      await asyncio.sleep(poll_interval)
-    raise TimeoutError(f"Task {self.id()} did not complete within {timeout} seconds.")
-
-  async def live_url(self, interactive: bool = True, embed: bool = False, timeout: int | None = None):
-    """Returns the live URL for the task."""
-    if self._task_response and self._task_response.live_url:
-      return _encode_url(self._task_response.live_url, interactive=interactive, embed=embed)
-
-    start_time = time.time()
-    while timeout is None or (time.time() - start_time) < timeout:
-      task_response = await self._client._get_task(self.id())
-      self._task_response = task_response
-      if task_response.live_url is not None:
-        return _encode_url(self._task_response.live_url, interactive=interactive, embed=embed)
-      await asyncio.sleep(1)
-
-    raise TimeoutError(f"Live URL not available for task {self.id()}.")
-
-  async def recording_url(self, timeout: int | None = None):
-    """Returns the recording URL for the task."""
-    if self._task_response and self._task_response.recording_url is not None:
-      return self._task_response.recording_url
-
-    start_time = time.time()
-    while timeout is None or (time.time() - start_time) < timeout:
-      task_response = await self._client._get_task(self.id())
-      self._task_response = task_response
-      if task_response.recording_url is not None:
-        return task_response.recording_url
-      await asyncio.sleep(1)
-
-    raise TimeoutError(f"Recording URL not available for task {self.id()}.")
+    browser_session: BrowserSessionResponse = Field(
+        description="The browser session associated with this handle."
+    )
 
+    @deprecated("session_id is deprecated, use profile_id instead")
+    def session_id(self):
+        """Returns the session ID for the browser session."""
+        return self.profile_id()
 
-class SmoothAsyncClient(BaseClient):
-  """An asynchronous client for the API."""
-
-  def __init__(self, api_key: str | None = None, base_url: str = BASE_URL, api_version: str = "v1", timeout: int = 30):
-    """Initializes the asynchronous client."""
-    super().__init__(api_key, base_url, api_version)
-    self._client = httpx.AsyncClient(headers=self.headers, timeout=timeout)
-
-  async def __aenter__(self):
-    """Enters the asynchronous context manager."""
-    return self
-
-  async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any):
-    """Exits the asynchronous context manager."""
-    await self.close()
-
-  async def _submit_task(self, payload: TaskRequest) -> TaskResponse:
-    """Submits a task to be run asynchronously."""
-    try:
-      response = await self._client.post(f"{self.base_url}/task", json=payload.model_dump(exclude_none=True))
-      data = self._handle_response(response)
-      return TaskResponse(**data["r"])
-    except httpx.RequestError as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  async def _get_task(self, task_id: str) -> TaskResponse:
-    """Retrieves the status and result of a task asynchronously."""
-    if not task_id:
-      raise ValueError("Task ID cannot be empty.")
-
-    try:
-      response = await self._client.get(f"{self.base_url}/task/{task_id}")
-      data = self._handle_response(response)
-      return TaskResponse(**data["r"])
-    except httpx.RequestError as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  async def run(
-    self,
-    task: str,
-    response_model: dict[str, Any] | Type[BaseModel] | None = None,
-    url: str | None = None,
-    metadata: dict[str, str | int | float | bool] | None = None,
-    files: list[str] | None = None,
-    agent: Literal["smooth"] = "smooth",
-    max_steps: int = 32,
-    device: Literal["desktop", "mobile"] = "mobile",
-    allowed_urls: list[str] | None = None,
-    enable_recording: bool = False,
-    session_id: str | None = None,
-    profile_id: str | None = None,
-    profile_read_only: bool = False,
-    stealth_mode: bool = False,
-    proxy_server: str | None = None,
-    proxy_username: str | None = None,
-    proxy_password: str | None = None,
-    experimental_features: dict[str, Any] | None = None,
-  ) -> AsyncTaskHandle:
-    """Runs a task and returns a handle to the task asynchronously.
-
-    This method submits a task and returns an `AsyncTaskHandle` object
-    that can be used to get the result of the task.
+    def profile_id(self):
+        """Returns the profile ID for the browser session."""
+        return self.browser_session.profile_id
 
-    Args:
-        task: The task to run.
-        response_model: If provided, the schema describing the desired output structure.
-        url: The starting URL for the task. If not provided, the agent will infer it from the task.
-        metadata: A dictionary containing variables or parameters that will be passed to the agent.
-        files: A dictionary of file names to their url or base64-encoded content to be used by the agent.
-        agent: The agent to use for the task.
-        max_steps: Maximum number of steps the agent can take (max 64).
-        device: Device type for the task. Default is mobile.
-        allowed_urls: List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*).
-          If None, all URLs are allowed.
-        enable_recording: Enable video recording of the task execution.
-        session_id: (Deprecated, now `profile_id`) Browser session ID to use.
-        profile_id: Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials.
-        profile_read_only: If true, the profile specified by `profile_id` will be loaded in read-only mode.
-        stealth_mode: Run the browser in stealth mode.
-        proxy_server: Proxy server url to route browser traffic through.
-        proxy_username: Proxy server username.
-        proxy_password: Proxy server password.
-        experimental_features: Experimental features to enable for the task.
+    def live_url(self, interactive: bool = True, embed: bool = False):
+        """Returns the live URL for the browser session."""
+        if self.browser_session.live_url:
+            return _encode_url(
+                self.browser_session.live_url, interactive=interactive, embed=embed
+            )
+        return None
 
-    Returns:
-        A handle to the running task.
+    def live_id(self):
+        """Returns the live ID for the browser session."""
+        return self.browser_session.live_id
 
-    Raises:
-        ApiException: If the API request fails.
-    """
-    payload = TaskRequest(
-      task=task,
-      response_model=response_model.model_json_schema() if issubclass(response_model, BaseModel) else response_model,
-      url=url,
-      metadata=metadata,
-      files=files,
-      agent=agent,
-      max_steps=max_steps,
-      device=device,
-      allowed_urls=allowed_urls,
-      enable_recording=enable_recording,
-      profile_id=profile_id or session_id,
-      profile_read_only=profile_read_only,
-      stealth_mode=stealth_mode,
-      proxy_server=proxy_server,
-      proxy_username=proxy_username,
-      proxy_password=proxy_password,
-      experimental_features=experimental_features,
-    )
-
-    initial_response = await self._submit_task(payload)
-    return AsyncTaskHandle(initial_response.id, self)
-
-  async def open_session(
-    self, profile_id: str | None = None, session_id: str | None = None, live_view: bool = True
-  ) -> BrowserSessionHandle:
-    """Opens an interactive browser instance asynchronously.
 
-    Args:
-        session_id: (Deprecated, now `profile_id`) The session ID to associate with the browser.
-        profile_id: The profile ID to associate with the browser.
-        live_view: Whether to enable live view for the session.
+class TaskHandle:
+    """A handle to a running task."""
+
+    def __init__(self, task_id: str, client: "SmoothClient"):
+        """Initializes the task handle."""
+        self._client = client
+        self._task_response: TaskResponse | None = None
+
+        self._id = task_id
+
+    def id(self):
+        """Returns the task ID."""
+        return self._id
+
+    def stop(self):
+        """Stops the task."""
+        self._client._delete_task(self._id)
+
+    def result(
+        self, timeout: int | None = None, poll_interval: float = 1
+    ) -> TaskResponse:
+        """Waits for the task to complete and returns the result."""
+        if self._task_response and self._task_response.status not in [
+            "running",
+            "waiting",
+        ]:
+            return self._task_response
+
+        if timeout is not None and timeout < 1:
+            raise ValueError("Timeout must be at least 1 second.")
+        if poll_interval < 0.1:
+            raise ValueError("Poll interval must be at least 100 milliseconds.")
+
+        start_time = time.time()
+        while timeout is None or (time.time() - start_time) < timeout:
+            task_response = self._client._get_task(self.id())
+            self._task_response = task_response
+            if task_response.status not in ["running", "waiting"]:
+                return task_response
+            time.sleep(poll_interval)
+        raise TimeoutError(
+            f"Task {self.id()} did not complete within {timeout} seconds."
+        )
+
+    def live_url(
+        self, interactive: bool = False, embed: bool = False, timeout: int | None = None
+    ):
+        """Returns the live URL for the task."""
+        if self._task_response and self._task_response.live_url:
+            return _encode_url(
+                self._task_response.live_url, interactive=interactive, embed=embed
+            )
+
+        start_time = time.time()
+        while timeout is None or (time.time() - start_time) < timeout:
+            task_response = self._client._get_task(self.id())
+            self._task_response = task_response
+            if self._task_response.live_url:
+                return _encode_url(
+                    self._task_response.live_url, interactive=interactive, embed=embed
+                )
+            time.sleep(1)
+
+        raise TimeoutError(f"Live URL not available for task {self.id()}.")
+
+    def recording_url(self, timeout: int | None = None) -> str:
+        """Returns the recording URL for the task."""
+        if self._task_response and self._task_response.recording_url is not None:
+            return self._task_response.recording_url
+
+        start_time = time.time()
+        while timeout is None or (time.time() - start_time) < timeout:
+            task_response = self._client._get_task(self.id())
+            self._task_response = task_response
+            if task_response.recording_url is not None:
+                if not task_response.recording_url:
+                    raise ApiError(
+                        status_code=404,
+                        detail=(
+                            f"Recording URL not available for task {self.id()}."
+                            " Set `enable_recording=True` when creating the task to enable it."
+                        ),
+                    )
+                return task_response.recording_url
+            time.sleep(1)
+        raise TimeoutError(f"Recording URL not available for task {self.id()}.")
+
+    def downloads_url(self, timeout: int | None = None) -> str:
+        """Returns the downloads URL for the task."""
+        if self._task_response and self._task_response.downloads_url is not None:
+            return self._task_response.downloads_url
+
+        start_time = time.time()
+        while timeout is None or (time.time() - start_time) < timeout:
+            task_response = self._client._get_task(
+                self.id(), query_params={"downloads": "true"}
+            )
+            self._task_response = task_response
+            if task_response.downloads_url is not None:
+                if not task_response.downloads_url:
+                    raise ApiError(
+                        status_code=404,
+                        detail=(
+                            f"Downloads URL not available for task {self.id()}."
+                            " Make sure the task downloaded files during its execution."
+                        ),
+                    )
+                return task_response.downloads_url
+            time.sleep(1)
+        raise TimeoutError(f"Downloads URL not available for task {self.id()}.")
 
-    Returns:
-        The browser session details, including the live URL.
 
-    Raises:
-        ApiException: If the API request fails.
-    """
-    try:
-      response = await self._client.post(
-        f"{self.base_url}/browser/session",
-        json=BrowserSessionRequest(profile_id=profile_id or session_id, live_view=live_view).model_dump(exclude_none=True),
-      )
-      data = self._handle_response(response)
-      return BrowserSessionHandle(browser_session=BrowserSessionResponse(**data["r"]))
-    except httpx.RequestError as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  async def close_session(self, live_id: str):
-    """Closes a browser session."""
-    try:
-      response = await self._client.delete(f"{self.base_url}/browser/session/{live_id}")
-      self._handle_response(response)
-    except httpx.RequestError as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  async def list_profiles(self):
-    """Lists all browser profiles for the user.
+class SmoothClient(BaseClient):
+    """A synchronous client for the API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = BASE_URL,
+        api_version: str = "v1",
+    ):
+        """Initializes the synchronous client."""
+        super().__init__(api_key, base_url, api_version)
+        self._session = requests.Session()
+        self._session.headers.update(self.headers)
+
+    def __enter__(self):
+        """Enters the synchronous context manager."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any):
+        """Exits the synchronous context manager."""
+        self.close()
+
+    def close(self):
+        """Close the session."""
+        if hasattr(self, "_session"):
+            self._session.close()
+
+    def _submit_task(self, payload: TaskRequest) -> TaskResponse:
+        """Submits a task to be run."""
+        try:
+            response = self._session.post(
+                f"{self.base_url}/task", json=payload.model_dump()
+            )
+            data = self._handle_response(response)
+            return TaskResponse(**data["r"])
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    def _get_task(
+        self, task_id: str, query_params: dict[str, Any] | None = None
+    ) -> TaskResponse:
+        """Retrieves the status and result of a task."""
+        if not task_id:
+            raise ValueError("Task ID cannot be empty.")
+
+        try:
+            url = f"{self.base_url}/task/{task_id}"
+            response = self._session.get(url, params=query_params)
+            data = self._handle_response(response)
+            return TaskResponse(**data["r"])
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    def _delete_task(self, task_id: str):
+        """Deletes a task."""
+        if not task_id:
+            raise ValueError("Task ID cannot be empty.")
+
+        try:
+            response = self._session.delete(f"{self.base_url}/task/{task_id}")
+            self._handle_response(response)
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    def run(
+        self,
+        task: str,
+        response_model: dict[str, Any] | Type[BaseModel] | None = None,
+        url: str | None = None,
+        metadata: dict[str, str | int | float | bool] | None = None,
+        files: list[str] | None = None,
+        agent: Literal["smooth"] = "smooth",
+        max_steps: int = 32,
+        device: Literal["desktop", "mobile"] = "mobile",
+        allowed_urls: list[str] | None = None,
+        enable_recording: bool = True,
+        session_id: str | None = None,
+        profile_id: str | None = None,
+        profile_read_only: bool = False,
+        stealth_mode: bool = False,
+        proxy_server: str | None = None,
+        proxy_username: str | None = None,
+        proxy_password: str | None = None,
+        certificates: list[Certificate] | None = None,
+        use_adblock: bool | None = True,
+        additional_tools: dict[str, dict[str, Any] | None] | None = None,
+        experimental_features: dict[str, Any] | None = None,
+        extensions: list[str] | None = None,
+    ) -> TaskHandle:
+        """Runs a task and returns a handle to the task.
+
+        This method submits a task and returns a `TaskHandle` object
+        that can be used to get the result of the task.
+
+        Args:
+            task: The task to run.
+            response_model: If provided, the schema describing the desired output structure.
+            url: The starting URL for the task. If not provided, the agent will infer it from the task.
+            metadata: A dictionary containing variables or parameters that will be passed to the agent.
+            files: A list of file ids to pass to the agent.
+            agent: The agent to use for the task.
+            max_steps: Maximum number of steps the agent can take (max 64).
+            device: Device type for the task. Default is mobile.
+            allowed_urls: List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*).
+              If None, all URLs are allowed.
+            enable_recording: Enable video recording of the task execution.
+            session_id: (Deprecated, now `profile_id`) Browser session ID to use.
+            profile_id: Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials.
+            profile_read_only: If true, the profile specified by `profile_id` will be loaded in read-only mode.
+            stealth_mode: Run the browser in stealth mode.
+            proxy_server: Proxy server address to route browser traffic through.
+            proxy_username: Proxy server username.
+            proxy_password: Proxy server password.
+            certificates: List of client certificates to use when accessing secure websites.
+              Each certificate is a dictionary with the following fields:
+              - `file` (required): p12 file object to be uploaded (e.g., open("cert.p12", "rb")).
+              - `password` (optional): Password to decrypt the certificate file, if password-protected.
+            use_adblock: Enable adblock for the browser session. Default is True.
+            additional_tools: Additional tools to enable for the task.
+            experimental_features: Experimental features to enable for the task.
+
+        Returns:
+            A handle to the running task.
+
+        Raises:
+            ApiException: If the API request fails.
+        """
+        payload = TaskRequest(
+            task=task,
+            response_model=response_model
+            if isinstance(response_model, dict | None)
+            else response_model.model_json_schema(),
+            url=url,
+            metadata=metadata,
+            files=files,
+            agent=agent,
+            max_steps=max_steps,
+            device=device,
+            allowed_urls=allowed_urls,
+            enable_recording=enable_recording,
+            profile_id=profile_id or session_id,
+            profile_read_only=profile_read_only,
+            stealth_mode=stealth_mode,
+            proxy_server=proxy_server,
+            proxy_username=proxy_username,
+            proxy_password=proxy_password,
+            certificates=_process_certificates(certificates),
+            use_adblock=use_adblock,
+            additional_tools=additional_tools,
+            experimental_features=experimental_features,
+            extensions=extensions,
+        )
+        initial_response = self._submit_task(payload)
+
+        return TaskHandle(initial_response.id, self)
+
+    def open_session(
+        self,
+        profile_id: str | None = None,
+        session_id: str | None = None,
+        live_view: bool = True,
+        device: Literal["desktop", "mobile"] = "desktop",
+        url: str | None = None,
+        proxy_server: str | None = None,
+        proxy_username: str | None = None,
+        proxy_password: str | None = None,
+    ) -> BrowserSessionHandle:
+        """Opens an interactive browser instance to interact with a specific browser profile.
+
+        Args:
+            profile_id: The profile ID to use for the session. If None, a new profile will be created.
+            session_id: (Deprecated, now `profile_id`) The session ID to associate with the browser.
+            live_view: Whether to enable live view for the session.
+            device: The device type to use for the browser session.
+            url: The URL to open in the browser session.
+            proxy_server: Proxy server address to route browser traffic through.
+            proxy_username: Proxy server username.
+            proxy_password: Proxy server password.
+
+        Returns:
+            The browser session details, including the live URL.
+
+        Raises:
+            ApiException: If the API request fails.
+        """
+        try:
+            response = self._session.post(
+                f"{self.base_url}/browser/session",
+                json=BrowserSessionRequest(
+                    profile_id=profile_id or session_id,
+                    live_view=live_view,
+                    device=device,
+                    url=url,
+                    proxy_server=proxy_server,
+                    proxy_username=proxy_username,
+                    proxy_password=proxy_password,
+                ).model_dump(),
+            )
+            data = self._handle_response(response)
+            return BrowserSessionHandle(
+                browser_session=BrowserSessionResponse(**data["r"])
+            )
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    def close_session(self, live_id: str):
+        """Closes a browser session."""
+        try:
+            response = self._session.delete(
+                f"{self.base_url}/browser/session/{live_id}"
+            )
+            self._handle_response(response)
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    def list_profiles(self):
+        """Lists all browser profiles for the user.
+
+        Returns:
+            A list of existing browser profiles.
+
+        Raises:
+            ApiException: If the API request fails.
+        """
+        try:
+            response = self._session.get(f"{self.base_url}/browser/profile")
+            data = self._handle_response(response)
+            return BrowserProfilesResponse(**data["r"])
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    @deprecated("list_sessions is deprecated, use list_profiles instead")
+    def list_sessions(self):
+        """Lists all browser profiles for the user."""
+        return self.list_profiles()
+
+    def delete_profile(self, profile_id: str):
+        """Delete a browser profile."""
+        try:
+            response = self._session.delete(
+                f"{self.base_url}/browser/profile/{profile_id}"
+            )
+            self._handle_response(response)
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    @deprecated("delete_session is deprecated, use delete_profile instead")
+    def delete_session(self, session_id: str):
+        """Delete a browser profile."""
+        self.delete_profile(session_id)
+
+    def upload_file(
+        self, file: io.IOBase, name: str | None = None, purpose: str | None = None
+    ) -> UploadFileResponse:
+        """Upload a file and return the file ID.
+
+        Args:
+            file: File object to be uploaded.
+            name: Optional custom name for the file. If not provided, the original file name will be used.
+            purpose: Optional short description of the file to describe its purpose (i.e., 'the bank statement pdf').
+
+        Returns:
+            The file ID assigned to the uploaded file.
+
+        Raises:
+            ValueError: If the file doesn't exist or can't be read.
+            ApiError: If the API request fails.
+        """
+        try:
+            name = name or getattr(file, "name", None)
+            if name is None:
+                raise ValueError(
+                    "File name must be provided or the file object must have a 'name' attribute."
+                )
+
+            if purpose:
+                data = {"file_purpose": purpose}
+            else:
+                data = None
+
+            files = {"file": (Path(name).name, file)}
+            response = self._session.post(
+                f"{self.base_url}/file", files=files, data=data
+            )
+            data = self._handle_response(response)
+            return UploadFileResponse(**data["r"])
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    def delete_file(self, file_id: str):
+        """Delete a file by its ID."""
+        try:
+            response = self._session.delete(f"{self.base_url}/file/{file_id}")
+            self._handle_response(response)
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    def upload_extension(self, file: io.IOBase, name: str | None = None) -> UploadExtensionResponse:
+        """Upload an extension and return the extension ID."""
+        try:
+            name = name or getattr(file, "name", None)
+            if name is None:
+                raise ValueError(
+                    "Extension name must be provided or the extension object must have a 'name' attribute."
+                )
+            files = {"file": (Path(name).name, file)}
+            response = self._session.post(f"{self.base_url}/browser/extension", files=files)
+            data = self._handle_response(response)
+            return UploadExtensionResponse(**data["r"])
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    def list_extensions(self) -> ListExtensionsResponse:
+        """List all extensions."""
+        try:
+            response = self._session.get(f"{self.base_url}/browser/extension")
+            data = self._handle_response(response)
+            return ListExtensionsResponse(**data["r"])
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    def delete_extension(self, extension_id: str):
+        """Delete an extension by its ID."""
+        try:
+            response = self._session.delete(f"{self.base_url}/browser/extension/{extension_id}")
+            self._handle_response(response)
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
 
-    Returns:
-        A list of existing browser profiles.
+# --- Asynchronous Client ---
 
-    Raises:
-        ApiException: If the API request fails.
-    """
-    try:
-      response = await self._client.get(f"{self.base_url}/browser/session")
-      data = self._handle_response(response)
-      return BrowserProfilesResponse(**data["r"])
-    except httpx.RequestError as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  @deprecated("list_sessions is deprecated, use list_profiles instead")
-  async def list_sessions(self):
-    """Lists all browser profiles for the user."""
-    return await self.list_profiles()
-
-  async def delete_profile(self, profile_id: str):
-    """Delete a browser profile."""
-    try:
-      response = await self._client.delete(f"{self.base_url}/browser/session/{profile_id}")
-      self._handle_response(response)
-    except httpx.RequestError as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  @deprecated("delete_session is deprecated, use delete_profile instead")
-  async def delete_session(self, session_id: str):
-    """Delete a browser profile."""
-    await self.delete_profile(session_id)
-
-  async def upload_file(self, file: io.IOBase, name: str | None = None, purpose: str | None = None) -> UploadFileResponse:
-    """Upload a file and return the file ID.
 
-    Args:
-        file: File object to be uploaded.
-        name: Optional custom name for the file. If not provided, the original file name will be used.
-        purpose: Optional short description of the file to describe its purpose (i.e., 'the bank statement pdf').
+class AsyncTaskHandle:
+    """An asynchronous handle to a running task."""
+
+    def __init__(self, task_id: str, client: "SmoothAsyncClient"):
+        """Initializes the asynchronous task handle."""
+        self._client = client
+        self._task_response: TaskResponse | None = None
+
+        self._id = task_id
+
+    def id(self):
+        """Returns the task ID."""
+        return self._id
+
+    async def stop(self):
+        """Stops the task."""
+        await self._client._delete_task(self._id)
+
+    async def result(
+        self, timeout: int | None = None, poll_interval: float = 1
+    ) -> TaskResponse:
+        """Waits for the task to complete and returns the result."""
+        if self._task_response and self._task_response.status not in [
+            "running",
+            "waiting",
+        ]:
+            return self._task_response
+
+        if timeout is not None and timeout < 1:
+            raise ValueError("Timeout must be at least 1 second.")
+        if poll_interval < 0.1:
+            raise ValueError("Poll interval must be at least 100 milliseconds.")
+
+        start_time = time.time()
+        while timeout is None or (time.time() - start_time) < timeout:
+            task_response = await self._client._get_task(self.id())
+            self._task_response = task_response
+            if task_response.status not in ["running", "waiting"]:
+                return task_response
+            await asyncio.sleep(poll_interval)
+        raise TimeoutError(
+            f"Task {self.id()} did not complete within {timeout} seconds."
+        )
+
+    async def live_url(
+        self, interactive: bool = False, embed: bool = False, timeout: int | None = None
+    ):
+        """Returns the live URL for the task."""
+        if self._task_response and self._task_response.live_url:
+            return _encode_url(
+                self._task_response.live_url, interactive=interactive, embed=embed
+            )
+
+        start_time = time.time()
+        while timeout is None or (time.time() - start_time) < timeout:
+            task_response = await self._client._get_task(self.id())
+            self._task_response = task_response
+            if self._task_response.live_url:
+                return _encode_url(
+                    self._task_response.live_url, interactive=interactive, embed=embed
+                )
+            await asyncio.sleep(1)
+
+        raise TimeoutError(f"Live URL not available for task {self.id()}.")
+
+    async def recording_url(self, timeout: int | None = None) -> str:
+        """Returns the recording URL for the task."""
+        if self._task_response and self._task_response.recording_url is not None:
+            return self._task_response.recording_url
+
+        start_time = time.time()
+        while timeout is None or (time.time() - start_time) < timeout:
+            task_response = await self._client._get_task(self.id())
+            self._task_response = task_response
+            if task_response.recording_url is not None:
+                if not task_response.recording_url:
+                    raise ApiError(
+                        status_code=404,
+                        detail=(
+                            f"Recording URL not available for task {self.id()}."
+                            " Set `enable_recording=True` when creating the task to enable it."
+                        ),
+                    )
+                return task_response.recording_url
+            await asyncio.sleep(1)
+
+        raise TimeoutError(f"Recording URL not available for task {self.id()}.")
+
+    async def downloads_url(self, timeout: int | None = None) -> str:
+        """Returns the downloads URL for the task."""
+        if self._task_response and self._task_response.downloads_url is not None:
+            return self._task_response.downloads_url
+
+        start_time = time.time()
+        while timeout is None or (time.time() - start_time) < timeout:
+            task_response = await self._client._get_task(
+                self.id(), query_params={"downloads": "true"}
+            )
+            self._task_response = task_response
+            if task_response.downloads_url is not None:
+                if not task_response.downloads_url:
+                    raise ApiError(
+                        status_code=404,
+                        detail=(
+                            f"Downloads URL not available for task {self.id()}."
+                            " Make sure the task downloaded files during its execution."
+                        ),
+                    )
+                return task_response.downloads_url
+            await asyncio.sleep(1)
+
+        raise TimeoutError(f"Downloads URL not available for task {self.id()}.")
 
-    Returns:
-        The file ID assigned to the uploaded file.
 
-    Raises:
-        ValueError: If the file doesn't exist or can't be read.
-        ApiError: If the API request fails.
-    """
-    try:
-      name = name or getattr(file, "name", None)
-      if name is None:
-        raise ValueError("File name must be provided or the file object must have a 'name' attribute.")
-
-      files = {"file": (Path(name).name, file)}
-      if purpose:
-        data = {"file_purpose": purpose}
-      else:
-        data = None
-      response = await self._client.post(f"{self.base_url}/file", files=files, data=data)
-      data = self._handle_response(response)
-      return UploadFileResponse(**data["r"])
-    except httpx.RequestError as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  async def delete_file(self, file_id: str):
-    """Delete a file by its ID."""
-    try:
-      response = await self._client.delete(f"{self.base_url}/file/{file_id}")
-      self._handle_response(response)
-    except httpx.RequestError as e:
-      logger.error(f"Request failed: {e}")
-      raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
-
-  async def close(self):
-    """Closes the async client session."""
-    await self._client.aclose()
+class SmoothAsyncClient(BaseClient):
+    """An asynchronous client for the API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = BASE_URL,
+        api_version: str = "v1",
+        timeout: int = 30,
+    ):
+        """Initializes the asynchronous client."""
+        super().__init__(api_key, base_url, api_version)
+        self._client = httpx.AsyncClient(headers=self.headers, timeout=timeout)
+
+    async def __aenter__(self):
+        """Enters the asynchronous context manager."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any):
+        """Exits the asynchronous context manager."""
+        await self.close()
+
+    async def _submit_task(self, payload: TaskRequest) -> TaskResponse:
+        """Submits a task to be run asynchronously."""
+        try:
+            response = await self._client.post(
+                f"{self.base_url}/task", json=payload.model_dump()
+            )
+            data = self._handle_response(response)
+            return TaskResponse(**data["r"])
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    async def _get_task(
+        self, task_id: str, query_params: dict[str, Any] | None = None
+    ) -> TaskResponse:
+        """Retrieves the status and result of a task asynchronously."""
+        if not task_id:
+            raise ValueError("Task ID cannot be empty.")
+
+        try:
+            url = f"{self.base_url}/task/{task_id}"
+            response = await self._client.get(url, params=query_params)
+            data = self._handle_response(response)
+            return TaskResponse(**data["r"])
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    async def _delete_task(self, task_id: str):
+        """Deletes a task asynchronously."""
+        if not task_id:
+            raise ValueError("Task ID cannot be empty.")
+
+        try:
+            response = await self._client.delete(f"{self.base_url}/task/{task_id}")
+            self._handle_response(response)
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    async def run(
+        self,
+        task: str,
+        response_model: dict[str, Any] | Type[BaseModel] | None = None,
+        url: str | None = None,
+        metadata: dict[str, str | int | float | bool] | None = None,
+        files: list[str] | None = None,
+        agent: Literal["smooth"] = "smooth",
+        max_steps: int = 32,
+        device: Literal["desktop", "mobile"] = "mobile",
+        allowed_urls: list[str] | None = None,
+        enable_recording: bool = True,
+        session_id: str | None = None,
+        profile_id: str | None = None,
+        profile_read_only: bool = False,
+        stealth_mode: bool = False,
+        proxy_server: str | None = None,
+        proxy_username: str | None = None,
+        proxy_password: str | None = None,
+        certificates: list[Certificate] | None = None,
+        use_adblock: bool | None = True,
+        additional_tools: dict[str, dict[str, Any] | None] | None = None,
+        experimental_features: dict[str, Any] | None = None,
+    ) -> AsyncTaskHandle:
+        """Runs a task and returns a handle to the task asynchronously.
+
+        This method submits a task and returns an `AsyncTaskHandle` object
+        that can be used to get the result of the task.
+
+        Args:
+            task: The task to run.
+            response_model: If provided, the schema describing the desired output structure.
+            url: The starting URL for the task. If not provided, the agent will infer it from the task.
+            metadata: A dictionary containing variables or parameters that will be passed to the agent.
+            files: A list of file ids to pass to the agent.
+            agent: The agent to use for the task.
+            max_steps: Maximum number of steps the agent can take (max 64).
+            device: Device type for the task. Default is mobile.
+            allowed_urls: List of allowed URL patterns using wildcard syntax (e.g., https://*example.com/*).
+              If None, all URLs are allowed.
+            enable_recording: Enable video recording of the task execution.
+            session_id: (Deprecated, now `profile_id`) Browser session ID to use.
+            profile_id: Browser profile ID to use. Each profile maintains its own state, such as cookies and login credentials.
+            profile_read_only: If true, the profile specified by `profile_id` will be loaded in read-only mode.
+            stealth_mode: Run the browser in stealth mode.
+            proxy_server: Proxy server address to route browser traffic through.
+            proxy_username: Proxy server username.
+            proxy_password: Proxy server password.
+            certificates: List of client certificates to use when accessing secure websites.
+              Each certificate is a dictionary with the following fields:
+              - `file` (required): p12 file object to be uploaded (e.g., open("cert.p12", "rb")).
+              - `password` (optional): Password to decrypt the certificate file.
+            use_adblock: Enable adblock for the browser session. Default is True.
+            additional_tools: Additional tools to enable for the task.
+            experimental_features: Experimental features to enable for the task.
+
+        Returns:
+            A handle to the running task.
+
+        Raises:
+            ApiException: If the API request fails.
+        """
+        payload = TaskRequest(
+            task=task,
+            response_model=response_model
+            if isinstance(response_model, dict | None)
+            else response_model.model_json_schema(),
+            url=url,
+            metadata=metadata,
+            files=files,
+            agent=agent,
+            max_steps=max_steps,
+            device=device,
+            allowed_urls=allowed_urls,
+            enable_recording=enable_recording,
+            profile_id=profile_id or session_id,
+            profile_read_only=profile_read_only,
+            stealth_mode=stealth_mode,
+            proxy_server=proxy_server,
+            proxy_username=proxy_username,
+            proxy_password=proxy_password,
+            certificates=_process_certificates(certificates),
+            use_adblock=use_adblock,
+            additional_tools=additional_tools,
+            experimental_features=experimental_features,
+        )
+
+        initial_response = await self._submit_task(payload)
+        return AsyncTaskHandle(initial_response.id, self)
+
+    async def open_session(
+        self,
+        profile_id: str | None = None,
+        session_id: str | None = None,
+        live_view: bool = True,
+        device: Literal["desktop", "mobile"] = "desktop",
+        url: str | None = None,
+        proxy_server: str | None = None,
+        proxy_username: str | None = None,
+        proxy_password: str | None = None,
+    ) -> BrowserSessionHandle:
+        """Opens an interactive browser instance asynchronously.
+
+        Args:
+            profile_id: The profile ID to use for the session. If None, a new profile will be created.
+            session_id: (Deprecated, now `profile_id`) The session ID to associate with the browser.
+            live_view: Whether to enable live view for the session.
+            device: The device type to use for the session. Defaults to "desktop".
+            url: The URL to open in the browser session.
+            proxy_server: Proxy server address to route browser traffic through.
+            proxy_username: Proxy server username.
+            proxy_password: Proxy server password.
+
+        Returns:
+            The browser session details, including the live URL.
+
+        Raises:
+            ApiException: If the API request fails.
+        """
+        try:
+            response = await self._client.post(
+                f"{self.base_url}/browser/session",
+                json=BrowserSessionRequest(
+                    profile_id=profile_id or session_id,
+                    live_view=live_view,
+                    device=device,
+                    url=url,
+                    proxy_server=proxy_server,
+                    proxy_username=proxy_username,
+                    proxy_password=proxy_password,
+                ).model_dump(),
+            )
+            data = self._handle_response(response)
+            return BrowserSessionHandle(
+                browser_session=BrowserSessionResponse(**data["r"])
+            )
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    async def close_session(self, live_id: str):
+        """Closes a browser session."""
+        try:
+            response = await self._client.delete(
+                f"{self.base_url}/browser/session/{live_id}"
+            )
+            self._handle_response(response)
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    async def list_profiles(self):
+        """Lists all browser profiles for the user.
+
+        Returns:
+            A list of existing browser profiles.
+
+        Raises:
+            ApiException: If the API request fails.
+        """
+        try:
+            response = await self._client.get(f"{self.base_url}/browser/profile")
+            data = self._handle_response(response)
+            return BrowserProfilesResponse(**data["r"])
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    @deprecated("list_sessions is deprecated, use list_profiles instead")
+    async def list_sessions(self):
+        """Lists all browser profiles for the user."""
+        return await self.list_profiles()
+
+    async def delete_profile(self, profile_id: str):
+        """Delete a browser profile."""
+        try:
+            response = await self._client.delete(
+                f"{self.base_url}/browser/profile/{profile_id}"
+            )
+            self._handle_response(response)
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    @deprecated("delete_session is deprecated, use delete_profile instead")
+    async def delete_session(self, session_id: str):
+        """Delete a browser profile."""
+        await self.delete_profile(session_id)
+
+    async def upload_file(
+        self, file: io.IOBase, name: str | None = None, purpose: str | None = None
+    ) -> UploadFileResponse:
+        """Upload a file and return the file ID.
+
+        Args:
+            file: File object to be uploaded.
+            name: Optional custom name for the file. If not provided, the original file name will be used.
+            purpose: Optional short description of the file to describe its purpose (i.e., 'the bank statement pdf').
+
+        Returns:
+            The file ID assigned to the uploaded file.
+
+        Raises:
+            ValueError: If the file doesn't exist or can't be read.
+            ApiError: If the API request fails.
+        """
+        try:
+            name = name or getattr(file, "name", None)
+            if name is None:
+                raise ValueError(
+                    "File name must be provided or the file object must have a 'name' attribute."
+                )
+
+            if purpose:
+                data = {"file_purpose": purpose}
+            else:
+                data = None
+
+            files = {"file": (Path(name).name, file)}
+            response = await self._client.post(
+                f"{self.base_url}/file", files=files, data=data
+            )
+            data = self._handle_response(response)
+            return UploadFileResponse(**data["r"])
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    async def delete_file(self, file_id: str):
+        """Delete a file by its ID."""
+        try:
+            response = await self._client.delete(f"{self.base_url}/file/{file_id}")
+            self._handle_response(response)
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    async def upload_extension(self, file: io.IOBase, name: str | None = None) -> UploadExtensionResponse:
+        """Upload an extension and return the extension ID."""
+        try:
+            name = name or getattr(file, "name", None)
+            if name is None:
+                raise ValueError(
+                    "File name must be provided or the file object must have a 'name' attribute."
+                )
+            files = {"file": (Path(name).name, file)}
+            response = await self._client.post(f"{self.base_url}/browser/extension", files=files)
+            data = self._handle_response(response)
+            return UploadExtensionResponse(**data["r"])
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    async def list_extensions(self) -> ListExtensionsResponse:
+        """List all extensions."""
+        try:
+            response = await self._client.get(f"{self.base_url}/browser/extension")
+            data = self._handle_response(response)
+            return ListExtensionsResponse(**data["r"])
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    async def delete_extension(self, extension_id: str):
+        """Delete an extension by its ID."""
+        try:
+            response = await self._client.delete(f"{self.base_url}/browser/extension/{extension_id}")
+            self._handle_response(response)
+        except httpx.RequestError as e:
+            logger.error(f"Request failed: {e}")
+            raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
+
+    async def close(self):
+        """Closes the async client session."""
+        await self._client.aclose()
 
 
 # Export public API
 __all__ = [
-  "SmoothClient",
-  "SmoothAsyncClient",
-  "TaskHandle",
-  "AsyncTaskHandle",
-  "BrowserSessionHandle",
-  "TaskRequest",
-  "TaskResponse",
-  "BrowserSessionRequest",
-  "BrowserSessionResponse",
-  "BrowserSessionsResponse",
-  "UploadFileResponse",
-  "ApiError",
-  "TimeoutError",
+    "SmoothClient",
+    "SmoothAsyncClient",
+    "TaskHandle",
+    "AsyncTaskHandle",
+    "BrowserSessionHandle",
+    "TaskRequest",
+    "TaskResponse",
+    "BrowserSessionRequest",
+    "BrowserSessionResponse",
+    "BrowserSessionsResponse",
+    "UploadFileResponse",
+    "UploadExtensionResponse",
+    "ListExtensionsResponse",
+    "Extension",
+    "Certificate",
+    "ApiError",
+    "TimeoutError",
 ]