cyberdesk 2.1.16__py3-none-any.whl → 2.1.18__py3-none-any.whl

cyberdesk/client.py

@@ -1,5 +1,5 @@
 """Cyberdesk Python SDK Client."""
-from typing import Optional, Dict, Any, Union, List
+from typing import Optional, Dict, Any, Union, List, TypeVar, Generic
 from uuid import UUID
 from pathlib import Path
 import httpx
@@ -155,10 +155,12 @@ __all__ = [
 DEFAULT_API_BASE_URL = "https://api.cyberdesk.io"
 
 
+T = TypeVar('T')
+
 @dataclass
-class ApiResponse:
+class ApiResponse(Generic[T]):
     """Wrapper for API responses."""
-    data: Optional[Any] = None
+    data: Optional[T] = None
     error: Optional[Any] = None
 
 
@@ -208,7 +210,7 @@ class MachinesAPI:
         *,
         created_at_from: Optional[Union[str, datetime]] = None,
         created_at_to: Optional[Union[str, datetime]] = None,
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseMachineResponse]:
         """List machines with optional filtering.
 
         Args:
@@ -217,6 +219,10 @@ class MachinesAPI:
             status: Machine status filter
             created_at_from: Optional start datetime (UTC or ISO string)
             created_at_to: Optional end datetime (UTC or ISO string)
+        
+        Returns:
+            ApiResponse with PaginatedResponseMachineResponse. Each machine includes
+            desktop parameters (machine_parameters, machine_sensitive_parameters) if configured.
         """
         try:
             response = await list_machines_v1_machines_get.asyncio(
@@ -239,8 +245,20 @@ class MachinesAPI:
         *,
         created_at_from: Optional[Union[str, datetime]] = None,
         created_at_to: Optional[Union[str, datetime]] = None,
-    ) -> ApiResponse:
-        """List machines with optional filtering (synchronous)."""
+    ) -> ApiResponse[PaginatedResponseMachineResponse]:
+        """List machines with optional filtering (synchronous).
+        
+        Args:
+            skip: Pagination skip
+            limit: Pagination limit
+            status: Machine status filter
+            created_at_from: Optional start datetime (UTC or ISO string)
+            created_at_to: Optional end datetime (UTC or ISO string)
+        
+        Returns:
+            ApiResponse with PaginatedResponseMachineResponse. Each machine includes
+            desktop parameters (machine_parameters, machine_sensitive_parameters) if configured.
+        """
         try:
             response = list_machines_v1_machines_get.sync(
                 client=self.client,
@@ -254,8 +272,19 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def create(self, data: MachineCreate) -> ApiResponse:
-        """Create a new machine."""
+    async def create(self, data: MachineCreate) -> ApiResponse[MachineResponse]:
+        """Create a new machine.
+        
+        Args:
+            data: MachineCreate object with:
+                - fingerprint: Unique machine fingerprint
+                - unkey_key_id: API key ID for authentication
+                - name: Optional machine name
+                - machine_parameters: Optional dict of desktop parameters
+                - machine_sensitive_parameters: Optional dict of sensitive desktop parameters
+                  (provide actual values, they'll be stored in Basis Theory)
+                - hostname, os_info, version: Optional machine metadata
+        """
         try:
             response = await create_machine_v1_machines_post.asyncio(
                 client=self.client,
@@ -265,8 +294,19 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def create_sync(self, data: MachineCreate) -> ApiResponse:
-        """Create a new machine (synchronous)."""
+    def create_sync(self, data: MachineCreate) -> ApiResponse[MachineResponse]:
+        """Create a new machine (synchronous).
+        
+        Args:
+            data: MachineCreate object with:
+                - fingerprint: Unique machine fingerprint
+                - unkey_key_id: API key ID for authentication
+                - name: Optional machine name
+                - machine_parameters: Optional dict of desktop parameters
+                - machine_sensitive_parameters: Optional dict of sensitive desktop parameters
+                  (provide actual values, they'll be stored in Basis Theory)
+                - hostname, os_info, version: Optional machine metadata
+        """
         try:
             response = create_machine_v1_machines_post.sync(
                 client=self.client,
@@ -276,8 +316,16 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def get(self, machine_id: str) -> ApiResponse:
-        """Get a specific machine by ID."""
+    async def get(self, machine_id: str) -> ApiResponse[MachineResponse]:
+        """Get a specific machine by ID.
+        
+        Returns:
+            ApiResponse with MachineResponse including:
+                - Basic info: id, name, status, fingerprint, etc.
+                - machine_parameters: Dict of desktop parameters (if configured)
+                - machine_sensitive_parameters: Dict of sensitive parameter aliases (if configured)
+                - pools: List of pools this machine belongs to
+        """
         try:
             response = await get_machine_v1_machines_machine_id_get.asyncio(
                 client=self.client,
@@ -287,8 +335,16 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def get_sync(self, machine_id: str) -> ApiResponse:
-        """Get a specific machine by ID (synchronous)."""
+    def get_sync(self, machine_id: str) -> ApiResponse[MachineResponse]:
+        """Get a specific machine by ID (synchronous).
+        
+        Returns:
+            ApiResponse with MachineResponse including:
+                - Basic info: id, name, status, fingerprint, etc.
+                - machine_parameters: Dict of desktop parameters (if configured)
+                - machine_sensitive_parameters: Dict of sensitive parameter aliases (if configured)
+                - pools: List of pools this machine belongs to
+        """
         try:
             response = get_machine_v1_machines_machine_id_get.sync(
                 client=self.client,
@@ -298,12 +354,30 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def update(self, machine_id: str, data: MachineUpdate) -> ApiResponse:
+    async def update(self, machine_id: str, data: MachineUpdate) -> ApiResponse[MachineResponse]:
         """Update a machine.
-
-        Note: linked_keepalive_machine_id is not writable; it is managed by
-        Cyberdriver link events and will be set/cleared automatically by the
-        platform.
+        
+        Args:
+            machine_id: The machine ID to update
+            data: MachineUpdate object with fields to update:
+                - name: Optional machine name
+                - machine_parameters: Optional dict of machine-specific input values that 
+                  automatically populate runs on this desktop. Use {} to clear all.
+                - machine_sensitive_parameters: Optional dict of sensitive parameters 
+                  (provide actual values, they'll be stored in Basis Theory). Use {} to clear all.
+                - status, is_available, hostname, os_info, version: Other machine fields
+                - reserved_session_id: Set to null to clear reservation
+        
+        Desktop Parameters:
+            Machine parameters automatically merge into runs assigned to this machine,
+            overriding run-level input values. Use {param_name} or {$sensitive_param}
+            syntax in workflow prompts.
+        
+        Note: 
+            - linked_keepalive_machine_id is not writable; it is managed by
+              Cyberdriver link events and will be set/cleared automatically by the platform.
+            - For machine_sensitive_parameters, provide actual secret values. They will be
+              stored securely in Basis Theory and only aliases stored in the database.
         """
         try:
             response = await update_machine_v1_machines_machine_id_patch.asyncio(
@@ -315,12 +389,30 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def update_sync(self, machine_id: str, data: MachineUpdate) -> ApiResponse:
+    def update_sync(self, machine_id: str, data: MachineUpdate) -> ApiResponse[MachineResponse]:
         """Update a machine (synchronous).
-
-        Note: linked_keepalive_machine_id is not writable; it is managed by
-        Cyberdriver link events and will be set/cleared automatically by the
-        platform.
+        
+        Args:
+            machine_id: The machine ID to update
+            data: MachineUpdate object with fields to update:
+                - name: Optional machine name
+                - machine_parameters: Optional dict of machine-specific input values that 
+                  automatically populate runs on this desktop. Use {} to clear all.
+                - machine_sensitive_parameters: Optional dict of sensitive parameters 
+                  (provide actual values, they'll be stored in Basis Theory). Use {} to clear all.
+                - status, is_available, hostname, os_info, version: Other machine fields
+                - reserved_session_id: Set to null to clear reservation
+        
+        Desktop Parameters:
+            Machine parameters automatically merge into runs assigned to this machine,
+            overriding run-level input values. Use {param_name} or {$sensitive_param}
+            syntax in workflow prompts.
+        
+        Note: 
+            - linked_keepalive_machine_id is not writable; it is managed by
+              Cyberdriver link events and will be set/cleared automatically by the platform.
+            - For machine_sensitive_parameters, provide actual secret values. They will be
+              stored securely in Basis Theory and only aliases stored in the database.
         """
         try:
             response = update_machine_v1_machines_machine_id_patch.sync(
@@ -332,7 +424,7 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def clear_session(self, machine_id: str) -> ApiResponse:
+    async def clear_session(self, machine_id: str) -> ApiResponse[MachineResponse]:
         """Clear the machine's reserved session (cancels queued/running session runs).
 
         This sends reserved_session_id=null per API contract.
@@ -348,7 +440,7 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def clear_session_sync(self, machine_id: str) -> ApiResponse:
+    def clear_session_sync(self, machine_id: str) -> ApiResponse[MachineResponse]:
         """Clear the machine's reserved session (synchronous)."""
         try:
             update = MachineUpdate(reserved_session_id=None)
@@ -361,8 +453,15 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def delete(self, machine_id: str) -> ApiResponse:
-        """Delete a machine."""
+    async def delete(self, machine_id: str) -> ApiResponse[MachineResponse]:
+        """Delete a machine.
+        
+        Associated runs are preserved with machine_id set to NULL to maintain run history.
+        Connections and request logs are cascade deleted.
+        
+        If the machine has desktop sensitive parameters, they will be automatically
+        cleaned up from Basis Theory before deletion.
+        """
         try:
             await delete_machine_v1_machines_machine_id_delete.asyncio(
                 client=self.client,
@@ -372,8 +471,15 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def delete_sync(self, machine_id: str) -> ApiResponse:
-        """Delete a machine (synchronous)."""
+    def delete_sync(self, machine_id: str) -> ApiResponse[MachineResponse]:
+        """Delete a machine (synchronous).
+        
+        Associated runs are preserved with machine_id set to NULL to maintain run history.
+        Connections and request logs are cascade deleted.
+        
+        If the machine has desktop sensitive parameters, they will be automatically
+        cleaned up from Basis Theory before deletion.
+        """
         try:
             delete_machine_v1_machines_machine_id_delete.sync(
                 client=self.client,
@@ -383,7 +489,7 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def get_pools(self, machine_id: str) -> ApiResponse:
+    async def get_pools(self, machine_id: str) -> ApiResponse[List[PoolResponse]]:
         """Get all pools that a machine belongs to."""
         try:
             response = await get_machine_pools_v1_machines_machine_id_pools_get.asyncio(
@@ -394,7 +500,7 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def get_pools_sync(self, machine_id: str) -> ApiResponse:
+    def get_pools_sync(self, machine_id: str) -> ApiResponse[List[PoolResponse]]:
         """Get all pools that a machine belongs to (synchronous)."""
         try:
             response = get_machine_pools_v1_machines_machine_id_pools_get.sync(
@@ -405,7 +511,7 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def update_pools(self, machine_id: str, data: MachinePoolUpdate) -> ApiResponse:
+    async def update_pools(self, machine_id: str, data: MachinePoolUpdate) -> ApiResponse[List[PoolResponse]]:
         """Update a machine's pool assignments.
         
         This replaces all existing pool assignments with the new ones.
@@ -427,7 +533,7 @@ class MachinesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def update_pools_sync(self, machine_id: str, data: MachinePoolUpdate) -> ApiResponse:
+    def update_pools_sync(self, machine_id: str, data: MachinePoolUpdate) -> ApiResponse[List[PoolResponse]]:
         """Update a machine's pool assignments (synchronous).
         
         This replaces all existing pool assignments with the new ones.
@@ -460,7 +566,7 @@ class PoolsAPI:
         self,
         skip: Optional[int] = None,
         limit: Optional[int] = None
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponsePoolResponse]:
         """List pools for the organization."""
         try:
             response = await list_pools_v1_pools_get.asyncio(
@@ -476,7 +582,7 @@ class PoolsAPI:
         self,
         skip: Optional[int] = None,
         limit: Optional[int] = None
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponsePoolResponse]:
         """List pools for the organization (synchronous)."""
         try:
             response = list_pools_v1_pools_get.sync(
@@ -488,7 +594,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def create(self, data: PoolCreate) -> ApiResponse:
+    async def create(self, data: PoolCreate) -> ApiResponse[PoolResponse]:
         """Create a new pool."""
         try:
             response = await create_pool_v1_pools_post.asyncio(
@@ -499,7 +605,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def create_sync(self, data: PoolCreate) -> ApiResponse:
+    def create_sync(self, data: PoolCreate) -> ApiResponse[PoolResponse]:
         """Create a new pool (synchronous)."""
         try:
             response = create_pool_v1_pools_post.sync(
@@ -510,7 +616,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def get(self, pool_id: str, include_machines: bool = False) -> ApiResponse:
+    async def get(self, pool_id: str, include_machines: bool = False) -> ApiResponse[Union[PoolResponse, PoolWithMachines]]:
         """Get a specific pool by ID.
         
         Args:
@@ -530,7 +636,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def get_sync(self, pool_id: str, include_machines: bool = False) -> ApiResponse:
+    def get_sync(self, pool_id: str, include_machines: bool = False) -> ApiResponse[Union[PoolResponse, PoolWithMachines]]:
         """Get a specific pool by ID (synchronous).
         
         Args:
@@ -550,7 +656,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def update(self, pool_id: str, data: PoolUpdate) -> ApiResponse:
+    async def update(self, pool_id: str, data: PoolUpdate) -> ApiResponse[PoolResponse]:
         """Update a pool's details."""
         try:
             response = await update_pool_v1_pools_pool_id_patch.asyncio(
@@ -562,7 +668,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def update_sync(self, pool_id: str, data: PoolUpdate) -> ApiResponse:
+    def update_sync(self, pool_id: str, data: PoolUpdate) -> ApiResponse[PoolResponse]:
         """Update a pool's details (synchronous)."""
         try:
             response = update_pool_v1_pools_pool_id_patch.sync(
@@ -574,7 +680,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def delete(self, pool_id: str) -> ApiResponse:
+    async def delete(self, pool_id: str) -> ApiResponse[PoolResponse]:
         """Delete a pool. This will not delete the machines in the pool."""
         try:
             await delete_pool_v1_pools_pool_id_delete.asyncio(
@@ -585,7 +691,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def delete_sync(self, pool_id: str) -> ApiResponse:
+    def delete_sync(self, pool_id: str) -> ApiResponse[PoolResponse]:
         """Delete a pool. This will not delete the machines in the pool (synchronous)."""
         try:
             delete_pool_v1_pools_pool_id_delete.sync(
@@ -596,7 +702,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def add_machines(self, pool_id: str, data: MachinePoolAssignment) -> ApiResponse:
+    async def add_machines(self, pool_id: str, data: MachinePoolAssignment) -> ApiResponse[PoolWithMachines]:
         """Add machines to a pool.
         
         Args:
@@ -616,7 +722,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def add_machines_sync(self, pool_id: str, data: MachinePoolAssignment) -> ApiResponse:
+    def add_machines_sync(self, pool_id: str, data: MachinePoolAssignment) -> ApiResponse[PoolWithMachines]:
         """Add machines to a pool (synchronous).
         
         Args:
@@ -636,7 +742,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def remove_machines(self, pool_id: str, data: MachinePoolAssignment) -> ApiResponse:
+    async def remove_machines(self, pool_id: str, data: MachinePoolAssignment) -> ApiResponse[PoolWithMachines]:
         """Remove machines from a pool.
         
         Args:
@@ -656,7 +762,7 @@ class PoolsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def remove_machines_sync(self, pool_id: str, data: MachinePoolAssignment) -> ApiResponse:
+    def remove_machines_sync(self, pool_id: str, data: MachinePoolAssignment) -> ApiResponse[PoolWithMachines]:
         """Remove machines from a pool (synchronous).
         
         Args:
@@ -692,7 +798,7 @@ class WorkflowsAPI:
         created_at_to: Optional[Union[str, datetime]] = None,
         updated_at_from: Optional[Union[str, datetime]] = None,
         updated_at_to: Optional[Union[str, datetime]] = None,
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseWorkflowResponse]:
         """List workflows with optional date-time filtering.
 
         Args:
@@ -726,7 +832,7 @@ class WorkflowsAPI:
         created_at_to: Optional[Union[str, datetime]] = None,
         updated_at_from: Optional[Union[str, datetime]] = None,
         updated_at_to: Optional[Union[str, datetime]] = None,
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseWorkflowResponse]:
         """List workflows (synchronous) with optional date-time filtering."""
         try:
             response = list_workflows_v1_workflows_get.sync(
@@ -742,7 +848,7 @@ class WorkflowsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def create(self, data: WorkflowCreate) -> ApiResponse:
+    async def create(self, data: WorkflowCreate) -> ApiResponse[WorkflowResponse]:
         """Create a new workflow."""
         try:
             response = await create_workflow_v1_workflows_post.asyncio(
@@ -753,7 +859,7 @@ class WorkflowsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def create_sync(self, data: WorkflowCreate) -> ApiResponse:
+    def create_sync(self, data: WorkflowCreate) -> ApiResponse[WorkflowResponse]:
         """Create a new workflow (synchronous)."""
         try:
             response = create_workflow_v1_workflows_post.sync(
@@ -764,7 +870,7 @@ class WorkflowsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def get(self, workflow_id: str) -> ApiResponse:
+    async def get(self, workflow_id: str) -> ApiResponse[WorkflowResponse]:
         """Get a specific workflow by ID."""
         try:
             response = await get_workflow_v1_workflows_workflow_id_get.asyncio(
@@ -775,7 +881,7 @@ class WorkflowsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def get_sync(self, workflow_id: str) -> ApiResponse:
+    def get_sync(self, workflow_id: str) -> ApiResponse[WorkflowResponse]:
         """Get a specific workflow by ID (synchronous)."""
         try:
             response = get_workflow_v1_workflows_workflow_id_get.sync(
@@ -786,7 +892,7 @@ class WorkflowsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def update(self, workflow_id: str, data: WorkflowUpdate) -> ApiResponse:
+    async def update(self, workflow_id: str, data: WorkflowUpdate) -> ApiResponse[WorkflowResponse]:
         """Update a workflow."""
         try:
             response = await update_workflow_v1_workflows_workflow_id_patch.asyncio(
@@ -798,7 +904,7 @@ class WorkflowsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def update_sync(self, workflow_id: str, data: WorkflowUpdate) -> ApiResponse:
+    def update_sync(self, workflow_id: str, data: WorkflowUpdate) -> ApiResponse[WorkflowResponse]:
         """Update a workflow (synchronous)."""
         try:
             response = update_workflow_v1_workflows_workflow_id_patch.sync(
@@ -810,7 +916,7 @@ class WorkflowsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def delete(self, workflow_id: str) -> ApiResponse:
+    async def delete(self, workflow_id: str) -> ApiResponse[WorkflowResponse]:
         """Delete a workflow."""
         try:
             await delete_workflow_v1_workflows_workflow_id_delete.asyncio(
@@ -821,7 +927,7 @@ class WorkflowsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def delete_sync(self, workflow_id: str) -> ApiResponse:
+    def delete_sync(self, workflow_id: str) -> ApiResponse[WorkflowResponse]:
         """Delete a workflow (synchronous)."""
         try:
             delete_workflow_v1_workflows_workflow_id_delete.sync(
@@ -851,7 +957,7 @@ class RunsAPI:
         created_at_from: Optional[Union[str, datetime]] = None,
         created_at_to: Optional[Union[str, datetime]] = None,
         fields: Optional[List[RunField]] = None,
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseRunResponse]:
         """List runs with optional filtering.
 
         Args:
@@ -896,7 +1002,7 @@ class RunsAPI:
         created_at_from: Optional[Union[str, datetime]] = None,
         created_at_to: Optional[Union[str, datetime]] = None,
         fields: Optional[List[RunField]] = None,
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseRunResponse]:
         """List runs with optional filtering (synchronous).
 
         See async variant for parameter docs. Supports `fields` projection.
@@ -918,7 +1024,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
 
-    async def retry(self, run_id: str, retry: RunRetry) -> ApiResponse:
+    async def retry(self, run_id: str, retry: RunRetry) -> ApiResponse[RunResponse]:
         """Retry an existing run in-place (same run_id).
 
         Clears previous outputs/history/output attachments, optionally replaces inputs/files,
@@ -934,7 +1040,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
 
-    def retry_sync(self, run_id: str, retry: RunRetry) -> ApiResponse:
+    def retry_sync(self, run_id: str, retry: RunRetry) -> ApiResponse[RunResponse]:
         """Retry an existing run in-place (synchronous)."""
         try:
             response = retry_run_v1_runs_run_id_retry_post.sync(
@@ -946,7 +1052,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def create(self, data: RunCreate) -> ApiResponse:
+    async def create(self, data: RunCreate) -> ApiResponse[RunResponse]:
         """Create a new run.
         
         Args:
@@ -974,7 +1080,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def create_sync(self, data: RunCreate) -> ApiResponse:
+    def create_sync(self, data: RunCreate) -> ApiResponse[RunResponse]:
         """Create a new run (synchronous).
         
         Args:
@@ -1002,7 +1108,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def get(self, run_id: str) -> ApiResponse:
+    async def get(self, run_id: str) -> ApiResponse[RunResponse]:
         """Get a specific run by ID."""
         try:
             response = await get_run_v1_runs_run_id_get.asyncio(
@@ -1013,7 +1119,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def get_sync(self, run_id: str) -> ApiResponse:
+    def get_sync(self, run_id: str) -> ApiResponse[RunResponse]:
         """Get a specific run by ID (synchronous)."""
         try:
             response = get_run_v1_runs_run_id_get.sync(
@@ -1024,7 +1130,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def update(self, run_id: str, data: RunUpdate) -> ApiResponse:
+    async def update(self, run_id: str, data: RunUpdate) -> ApiResponse[RunResponse]:
         """Update a run."""
         try:
             response = await update_run_v1_runs_run_id_patch.asyncio(
@@ -1036,7 +1142,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def update_sync(self, run_id: str, data: RunUpdate) -> ApiResponse:
+    def update_sync(self, run_id: str, data: RunUpdate) -> ApiResponse[RunResponse]:
         """Update a run (synchronous)."""
         try:
             response = update_run_v1_runs_run_id_patch.sync(
@@ -1048,7 +1154,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def delete(self, run_id: str) -> ApiResponse:
+    async def delete(self, run_id: str) -> ApiResponse[RunResponse]:
         """Delete a run."""
         try:
             await delete_run_v1_runs_run_id_delete.asyncio(
@@ -1059,7 +1165,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def delete_sync(self, run_id: str) -> ApiResponse:
+    def delete_sync(self, run_id: str) -> ApiResponse[RunResponse]:
         """Delete a run (synchronous)."""
         try:
             delete_run_v1_runs_run_id_delete.sync(
@@ -1070,7 +1176,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def bulk_create(self, data: RunBulkCreate) -> ApiResponse:
+    async def bulk_create(self, data: RunBulkCreate) -> ApiResponse[RunBulkCreateResponse]:
         """Create multiple runs with the same configuration.
         
         This method efficiently creates multiple runs:
@@ -1105,7 +1211,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def bulk_create_sync(self, data: RunBulkCreate) -> ApiResponse:
+    def bulk_create_sync(self, data: RunBulkCreate) -> ApiResponse[RunBulkCreateResponse]:
         """Create multiple runs with the same configuration (synchronous).
         
         This method efficiently creates multiple runs:
@@ -1140,7 +1246,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
 
-    async def chain(self, data: WorkflowChainCreate) -> ApiResponse:
+    async def chain(self, data: WorkflowChainCreate) -> ApiResponse[WorkflowChainResponse]:
         """Create a multi-step chain that runs on a single reserved session/machine.
 
         Args:
@@ -1160,7 +1266,7 @@ class RunsAPI:
         except Exception as e:
             return ApiResponse(error=e)
 
-    def chain_sync(self, data: WorkflowChainCreate) -> ApiResponse:
+    def chain_sync(self, data: WorkflowChainCreate) -> ApiResponse[WorkflowChainResponse]:
         """Create a multi-step chain (synchronous).
 
         Args:
@@ -1193,7 +1299,7 @@ class ConnectionsAPI:
         limit: Optional[int] = None,
         machine_id: Optional[str] = None,
         status: Optional[Union[str, ConnectionStatus]] = None
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseConnectionResponse]:
         """List connections with optional filtering."""
         try:
             # Handle status conversion
@@ -1217,7 +1323,7 @@ class ConnectionsAPI:
         limit: Optional[int] = None,
         machine_id: Optional[str] = None,
         status: Optional[Union[str, ConnectionStatus]] = None
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseConnectionResponse]:
         """List connections with optional filtering (synchronous)."""
         try:
             # Handle status conversion
@@ -1235,7 +1341,7 @@ class ConnectionsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def create(self, data: ConnectionCreate) -> ApiResponse:
+    async def create(self, data: ConnectionCreate) -> ApiResponse[ConnectionResponse]:
         """Create a new connection."""
         try:
             response = await create_connection_v1_connections_post.asyncio(
@@ -1246,7 +1352,7 @@ class ConnectionsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def create_sync(self, data: ConnectionCreate) -> ApiResponse:
+    def create_sync(self, data: ConnectionCreate) -> ApiResponse[ConnectionResponse]:
         """Create a new connection (synchronous)."""
         try:
             response = create_connection_v1_connections_post.sync(
@@ -1275,7 +1381,7 @@ class TrajectoriesAPI:
         created_at_to: Optional[Union[str, datetime]] = None,
         updated_at_from: Optional[Union[str, datetime]] = None,
         updated_at_to: Optional[Union[str, datetime]] = None,
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseTrajectoryResponse]:
         """List trajectories with optional filtering.
         
         Args:
@@ -1318,7 +1424,7 @@ class TrajectoriesAPI:
         created_at_to: Optional[Union[str, datetime]] = None,
         updated_at_from: Optional[Union[str, datetime]] = None,
         updated_at_to: Optional[Union[str, datetime]] = None,
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseTrajectoryResponse]:
         """List trajectories with optional filtering (synchronous).
         
         Args:
@@ -1350,7 +1456,7 @@ class TrajectoriesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def create(self, data: TrajectoryCreate) -> ApiResponse:
+    async def create(self, data: TrajectoryCreate) -> ApiResponse[TrajectoryResponse]:
         """Create a new trajectory.
         
         Note: Trajectories are created with is_approved=False by default.
@@ -1365,7 +1471,7 @@ class TrajectoriesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def create_sync(self, data: TrajectoryCreate) -> ApiResponse:
+    def create_sync(self, data: TrajectoryCreate) -> ApiResponse[TrajectoryResponse]:
         """Create a new trajectory (synchronous).
         
         Note: Trajectories are created with is_approved=False by default.
@@ -1380,7 +1486,7 @@ class TrajectoriesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def get(self, trajectory_id: str) -> ApiResponse:
+    async def get(self, trajectory_id: str) -> ApiResponse[TrajectoryResponse]:
         """Get a specific trajectory by ID."""
         try:
             response = await get_trajectory_v1_trajectories_trajectory_id_get.asyncio(
@@ -1391,7 +1497,7 @@ class TrajectoriesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def get_sync(self, trajectory_id: str) -> ApiResponse:
+    def get_sync(self, trajectory_id: str) -> ApiResponse[TrajectoryResponse]:
         """Get a specific trajectory by ID (synchronous)."""
         try:
             response = get_trajectory_v1_trajectories_trajectory_id_get.sync(
@@ -1402,7 +1508,7 @@ class TrajectoriesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def update(self, trajectory_id: str, data: TrajectoryUpdate) -> ApiResponse:
+    async def update(self, trajectory_id: str, data: TrajectoryUpdate) -> ApiResponse[TrajectoryResponse]:
         """Update a trajectory.
         
         You can update trajectory metadata (name, description), trajectory data (steps),
@@ -1419,7 +1525,7 @@ class TrajectoriesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def update_sync(self, trajectory_id: str, data: TrajectoryUpdate) -> ApiResponse:
+    def update_sync(self, trajectory_id: str, data: TrajectoryUpdate) -> ApiResponse[TrajectoryResponse]:
         """Update a trajectory (synchronous).
         
         You can update trajectory metadata (name, description), trajectory data (steps),
@@ -1436,7 +1542,7 @@ class TrajectoriesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def delete(self, trajectory_id: str) -> ApiResponse:
+    async def delete(self, trajectory_id: str) -> ApiResponse[TrajectoryResponse]:
         """Delete a trajectory."""
         try:
             await delete_trajectory_v1_trajectories_trajectory_id_delete.asyncio(
@@ -1447,7 +1553,7 @@ class TrajectoriesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def delete_sync(self, trajectory_id: str) -> ApiResponse:
+    def delete_sync(self, trajectory_id: str) -> ApiResponse[TrajectoryResponse]:
         """Delete a trajectory (synchronous)."""
         try:
             delete_trajectory_v1_trajectories_trajectory_id_delete.sync(
@@ -1458,7 +1564,7 @@ class TrajectoriesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def get_latest_for_workflow(self, workflow_id: str) -> ApiResponse:
+    async def get_latest_for_workflow(self, workflow_id: str) -> ApiResponse[TrajectoryResponse]:
         """Get the latest trajectory for a workflow."""
         try:
             response = await get_latest_trajectory_for_workflow_v1_workflows_workflow_id_latest_trajectory_get.asyncio(
@@ -1469,7 +1575,7 @@ class TrajectoriesAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def get_latest_for_workflow_sync(self, workflow_id: str) -> ApiResponse:
+    def get_latest_for_workflow_sync(self, workflow_id: str) -> ApiResponse[TrajectoryResponse]:
         """Get the latest trajectory for a workflow (synchronous)."""
         try:
             response = get_latest_trajectory_for_workflow_v1_workflows_workflow_id_latest_trajectory_get.sync(
@@ -1493,7 +1599,7 @@ class RunAttachmentsAPI:
         limit: Optional[int] = None,
         run_id: Optional[str] = None,
         attachment_type: Optional[AttachmentType] = None
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseRunAttachmentResponse]:
         """List run attachments with optional filtering."""
         try:
             response = await list_run_attachments_v1_run_attachments_get.asyncio(
@@ -1513,7 +1619,7 @@ class RunAttachmentsAPI:
         limit: Optional[int] = None,
         run_id: Optional[str] = None,
         attachment_type: Optional[AttachmentType] = None
-    ) -> ApiResponse:
+    ) -> ApiResponse[PaginatedResponseRunAttachmentResponse]:
         """List run attachments with optional filtering (synchronous)."""
         try:
             response = list_run_attachments_v1_run_attachments_get.sync(
@@ -1527,7 +1633,7 @@ class RunAttachmentsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def create(self, data: RunAttachmentCreate) -> ApiResponse:
+    async def create(self, data: RunAttachmentCreate) -> ApiResponse[RunAttachmentResponse]:
         """Create a new run attachment."""
         try:
             response = await create_run_attachment_v1_run_attachments_post.asyncio(
@@ -1538,7 +1644,7 @@ class RunAttachmentsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def create_sync(self, data: RunAttachmentCreate) -> ApiResponse:
+    def create_sync(self, data: RunAttachmentCreate) -> ApiResponse[RunAttachmentResponse]:
         """Create a new run attachment (synchronous)."""
         try:
             response = create_run_attachment_v1_run_attachments_post.sync(
@@ -1549,7 +1655,7 @@ class RunAttachmentsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def get(self, attachment_id: str) -> ApiResponse:
+    async def get(self, attachment_id: str) -> ApiResponse[RunAttachmentResponse]:
         """Get a specific run attachment by ID."""
         try:
             response = await get_run_attachment_v1_run_attachments_attachment_id_get.asyncio(
@@ -1560,7 +1666,7 @@ class RunAttachmentsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def get_sync(self, attachment_id: str) -> ApiResponse:
+    def get_sync(self, attachment_id: str) -> ApiResponse[RunAttachmentResponse]:
         """Get a specific run attachment by ID (synchronous)."""
         try:
             response = get_run_attachment_v1_run_attachments_attachment_id_get.sync(
@@ -1575,7 +1681,7 @@ class RunAttachmentsAPI:
         self, 
         attachment_id: str,
         expires_in: Optional[int] = None
-    ) -> ApiResponse:
+    ) -> ApiResponse[RunAttachmentDownloadUrlResponse]:
         """Get a signed download URL for a run attachment.
         
         The returned URL will trigger an automatic download when accessed in a browser.
@@ -1603,7 +1709,7 @@ class RunAttachmentsAPI:
         self, 
         attachment_id: str,
         expires_in: Optional[int] = None
-    ) -> ApiResponse:
+    ) -> ApiResponse[RunAttachmentDownloadUrlResponse]:
         """Get a signed download URL for a run attachment (synchronous).
         
         The returned URL will trigger an automatic download when accessed in a browser.
@@ -1627,7 +1733,7 @@ class RunAttachmentsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def download(self, attachment_id: str) -> ApiResponse:
+    async def download(self, attachment_id: str) -> ApiResponse[bytes]:
         """Download a run attachment file directly.
         
         This method returns the raw file content as bytes. For a download URL instead,
@@ -1648,7 +1754,7 @@ class RunAttachmentsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def download_sync(self, attachment_id: str) -> ApiResponse:
+    def download_sync(self, attachment_id: str) -> ApiResponse[bytes]:
         """Download a run attachment file directly (synchronous).
         
         This method returns the raw file content as bytes. For a download URL instead,
@@ -1669,7 +1775,7 @@ class RunAttachmentsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def update(self, attachment_id: str, data: RunAttachmentUpdate) -> ApiResponse:
+    async def update(self, attachment_id: str, data: RunAttachmentUpdate) -> ApiResponse[RunAttachmentResponse]:
         """Update a run attachment (e.g., set expiration)."""
         try:
             response = await update_run_attachment_v1_run_attachments_attachment_id_put.asyncio(
@@ -1681,7 +1787,7 @@ class RunAttachmentsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def update_sync(self, attachment_id: str, data: RunAttachmentUpdate) -> ApiResponse:
+    def update_sync(self, attachment_id: str, data: RunAttachmentUpdate) -> ApiResponse[RunAttachmentResponse]:
         """Update a run attachment (e.g., set expiration) (synchronous)."""
         try:
             response = update_run_attachment_v1_run_attachments_attachment_id_put.sync(
@@ -1693,7 +1799,7 @@ class RunAttachmentsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    async def delete(self, attachment_id: str) -> ApiResponse:
+    async def delete(self, attachment_id: str) -> ApiResponse[RunAttachmentResponse]:
         """Delete a run attachment."""
         try:
             await delete_run_attachment_v1_run_attachments_attachment_id_delete.asyncio(
@@ -1704,7 +1810,7 @@ class RunAttachmentsAPI:
         except Exception as e:
             return ApiResponse(error=e)
     
-    def delete_sync(self, attachment_id: str) -> ApiResponse:
+    def delete_sync(self, attachment_id: str) -> ApiResponse[RunAttachmentResponse]:
         """Delete a run attachment (synchronous)."""
         try:
             delete_run_attachment_v1_run_attachments_attachment_id_delete.sync(
@@ -1720,7 +1826,7 @@ class RunAttachmentsAPI:
         attachment_id: str,
         output_path: Optional[Union[str, Path]] = None,
         use_original_filename: bool = True
-    ) -> ApiResponse:
+    ) -> ApiResponse[Dict[str, Any]]:
         """Download and save a run attachment to a file.
         
         This is a convenience method that combines getting attachment info
@@ -1769,7 +1875,7 @@ class RunAttachmentsAPI:
         attachment_id: str,
         output_path: Optional[Union[str, Path]] = None,
         use_original_filename: bool = True
-    ) -> ApiResponse:
+    ) -> ApiResponse[Dict[str, Any]]:
         """Download and save a run attachment to a file (synchronous).
         
         This is a convenience method that combines getting attachment info