airweave-sdk 0.8.64__py3-none-any.whl → 0.8.66__py3-none-any.whl

airweave/source_connections/client.py

@@ -39,7 +39,13 @@ class SourceConnectionsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> typing.List[SourceConnectionListItem]:
         """
-        List source connections with minimal fields for performance.
+        Retrieve all source connections for your organization.
+
+        Returns a lightweight list of source connections with essential fields for
+        display and navigation. Use the collection filter to see connections within
+        a specific collection.
+
+        For full connection details including sync history, use the GET /{id} endpoint.
 
         Parameters
         ----------
@@ -47,8 +53,10 @@ class SourceConnectionsClient:
             Filter by collection readable ID
 
         skip : typing.Optional[int]
+            Number of connections to skip for pagination
 
         limit : typing.Optional[int]
+            Maximum number of connections to return (1-1000)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -56,21 +64,19 @@ class SourceConnectionsClient:
         Returns
         -------
         typing.List[SourceConnectionListItem]
-            Successful Response
+            List of source connections
 
         Examples
         --------
         from airweave import AirweaveSDK
 
         client = AirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
         client.source_connections.list(
             collection="collection",
-            skip=1,
-            limit=1,
+            skip=0,
+            limit=100,
         )
         """
         _response = self._raw_client.list(
@@ -93,45 +99,42 @@ class SourceConnectionsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> SourceConnection:
         """
-        Create a new source connection.
+        Create a new source connection to sync data from an external source.
 
-        The authentication configuration determines the flow:
-        - DirectAuthentication: Immediate creation with provided credentials
-        - OAuthBrowserAuthentication: Returns shell with authentication URL
-        - OAuthTokenAuthentication: Immediate creation with provided token
-        - AuthProviderAuthentication: Using external auth provider
+        The authentication method determines the creation flow:
 
-        BYOC (Bring Your Own Client) is detected when client_id and client_secret
-        are provided in OAuthBrowserAuthentication.
+        - **Direct**: Provide credentials (API key, token) directly. Connection is created immediately.
+        - **OAuth Browser**: Returns a connection with an `auth_url` to redirect users for authentication.
+        - **OAuth Token**: Provide an existing OAuth token. Connection is created immediately.
+        - **Auth Provider**: Use a pre-configured auth provider (e.g., Composio, Pipedream).
 
-        sync_immediately defaults:
-        - True for: direct, oauth_token, auth_provider
-        - False for: oauth_browser, oauth_byoc (these sync after authentication)
+        After successful authentication, data sync can begin automatically or on-demand.
 
         Parameters
         ----------
         short_name : str
-            Source identifier (e.g., 'slack', 'github')
+            Source type identifier (e.g., 'slack', 'github', 'notion')
 
         readable_collection_id : str
-            Collection readable ID
+            The readable ID of the collection to add this connection to
 
         name : typing.Optional[str]
-            Connection name (defaults to '{Source Name} Connection')
+            Display name for the connection. If not provided, defaults to '{Source Name} Connection'.
 
         description : typing.Optional[str]
-            Connection description
+            Optional description of what this connection is used for
 
         config : typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]]
-            Source-specific configuration
+            Source-specific configuration (e.g., repository name, filters)
 
         schedule : typing.Optional[ScheduleConfig]
+            Optional sync schedule configuration
 
         sync_immediately : typing.Optional[bool]
             Run initial sync after creation. Defaults to True for direct/token/auth_provider, False for OAuth browser/BYOC flows (which sync after authentication)
 
         authentication : typing.Optional[Authentication]
-            Authentication config (defaults to OAuth browser flow for OAuth sources)
+            Authentication configuration. Type is auto-detected from provided fields.
 
         redirect_url : typing.Optional[str]
             URL to redirect to after OAuth flow completes (only used for OAuth flows)
@@ -142,20 +145,18 @@ class SourceConnectionsClient:
         Returns
         -------
         SourceConnection
-            Successful Response
+            Created source connection
 
         Examples
         --------
         from airweave import AirweaveSDK
 
         client = AirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
         client.source_connections.create(
-            short_name="short_name",
-            readable_collection_id="readable_collection_id",
+            short_name="github",
+            readable_collection_id="customer-support-tickets-x7k9m",
         )
         """
         _response = self._raw_client.create(
@@ -176,11 +177,18 @@ class SourceConnectionsClient:
         self, source_connection_id: str, *, request_options: typing.Optional[RequestOptions] = None
     ) -> SourceConnection:
         """
-        Get a source connection with optional depth expansion.
+        Retrieve details of a specific source connection.
+
+        Returns complete information about the connection including:
+        - Configuration settings
+        - Authentication status
+        - Sync schedule and history
+        - Entity statistics
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection (UUID)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -188,19 +196,17 @@ class SourceConnectionsClient:
         Returns
         -------
         SourceConnection
-            Successful Response
+            Source connection details
 
         Examples
         --------
         from airweave import AirweaveSDK
 
         client = AirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
         client.source_connections.get(
-            source_connection_id="source_connection_id",
+            source_connection_id="550e8400-e29b-41d4-a716-446655440000",
         )
         """
         _response = self._raw_client.get(source_connection_id, request_options=request_options)
@@ -210,11 +216,19 @@ class SourceConnectionsClient:
         self, source_connection_id: str, *, request_options: typing.Optional[RequestOptions] = None
     ) -> SourceConnection:
         """
-        Delete a source connection and all related data.
+        Permanently delete a source connection and all its synced data.
+
+        This operation:
+        - Removes all entities synced from this source from the vector database
+        - Cancels any scheduled or running sync jobs
+        - Deletes the connection configuration and credentials
+
+        **Warning**: This action cannot be undone. All synced data will be permanently deleted.
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection to delete (UUID)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -222,19 +236,17 @@ class SourceConnectionsClient:
         Returns
         -------
         SourceConnection
-            Successful Response
+            Deleted source connection
 
         Examples
         --------
         from airweave import AirweaveSDK
 
         client = AirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
         client.source_connections.delete(
-            source_connection_id="source_connection_id",
+            source_connection_id="550e8400-e29b-41d4-a716-446655440000",
         )
         """
         _response = self._raw_client.delete(source_connection_id, request_options=request_options)
@@ -252,29 +264,35 @@ class SourceConnectionsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> SourceConnection:
         """
-        Update a source connection.
+        Update an existing source connection's configuration.
 
-        Updateable fields:
-        - name, description
-        - config_fields
-        - cron_schedule
-        - auth_fields (direct auth only)
+        You can modify:
+        - **Name and description**: Display information
+        - **Configuration**: Source-specific settings (e.g., repository name, filters)
+        - **Schedule**: Cron expression for automatic syncs
+        - **Authentication**: Update credentials (direct auth only)
+
+        Only include the fields you want to change; omitted fields retain their current values.
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection to update (UUID)
 
         name : typing.Optional[str]
+            Updated display name for the connection
 
         description : typing.Optional[str]
+            Updated description
 
         config : typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]]
-            Source-specific configuration
+            Updated source-specific configuration
 
         schedule : typing.Optional[ScheduleConfig]
+            Updated sync schedule configuration
 
         authentication : typing.Optional[Authentication]
-            Authentication config (defaults to OAuth browser flow for OAuth sources)
+            Updated authentication credentials (direct auth only)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -282,19 +300,17 @@ class SourceConnectionsClient:
         Returns
         -------
         SourceConnection
-            Successful Response
+            Updated source connection
 
         Examples
         --------
         from airweave import AirweaveSDK
 
         client = AirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
         client.source_connections.update(
-            source_connection_id="source_connection_id",
+            source_connection_id="550e8400-e29b-41d4-a716-446655440000",
         )
         """
         _response = self._raw_client.update(
@@ -316,25 +332,22 @@ class SourceConnectionsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> SourceConnectionJob:
         """
-        Trigger a sync run for a source connection.
+        Trigger a data synchronization job for a source connection.
 
-        Runs are always executed through Temporal workflow engine.
+        Starts an asynchronous sync job that pulls the latest data from the connected
+        source. The job runs in the background and you can monitor its progress using
+        the jobs endpoint.
 
-        Args:
-            db: Database session
-            source_connection_id: ID of the source connection to run
-            ctx: API context with organization and user information
-            guard_rail: Guard rail service for usage limits
-            force_full_sync: If True, forces a full sync with orphaned entity cleanup
-                            for continuous syncs. Raises 400 error if used on
-                            non-continuous syncs (which are always full syncs).
+        For continuous sync connections, this performs an incremental sync by default.
+        Use `force_full_sync=true` to perform a complete re-sync of all data.
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection to sync (UUID)
 
         force_full_sync : typing.Optional[bool]
-            Force a full sync ignoring cursor data instead of waiting for the daily cleanup schedule. Only allowed for continuous syncs.
+            Force a full sync ignoring cursor data. Only applies to continuous sync connections. Non-continuous connections always perform full syncs.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -342,20 +355,18 @@ class SourceConnectionsClient:
         Returns
         -------
         SourceConnectionJob
-            Successful Response
+            Created sync job
 
         Examples
         --------
         from airweave import AirweaveSDK
 
         client = AirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
         client.source_connections.run(
-            source_connection_id="source_connection_id",
-            force_full_sync=True,
+            source_connection_id="550e8400-e29b-41d4-a716-446655440000",
+            force_full_sync=False,
         )
         """
         _response = self._raw_client.run(
@@ -371,13 +382,26 @@ class SourceConnectionsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> typing.List[SourceConnectionJob]:
         """
-        Get sync jobs for a source connection.
+        Retrieve the sync job history for a source connection.
+
+        Returns a list of sync jobs ordered by creation time (newest first). Each job
+        includes status, timing information, and entity counts.
+
+        Job statuses:
+        - **PENDING**: Job is queued and waiting to start
+        - **RUNNING**: Sync is actively pulling and processing data
+        - **COMPLETED**: Sync finished successfully
+        - **FAILED**: Sync encountered an error
+        - **CANCELLED**: Sync was manually cancelled
+        - **CANCELLING**: Cancellation has been requested
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection (UUID)
 
         limit : typing.Optional[int]
+            Maximum number of jobs to return (1-1000)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -385,20 +409,18 @@ class SourceConnectionsClient:
         Returns
         -------
         typing.List[SourceConnectionJob]
-            Successful Response
+            List of sync jobs
 
         Examples
         --------
         from airweave import AirweaveSDK
 
         client = AirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
         client.source_connections.get_source_connection_jobs(
-            source_connection_id="source_connection_id",
-            limit=1,
+            source_connection_id="550e8400-e29b-41d4-a716-446655440000",
+            limit=100,
         )
         """
         _response = self._raw_client.get_source_connection_jobs(
@@ -410,17 +432,21 @@ class SourceConnectionsClient:
         self, source_connection_id: str, job_id: str, *, request_options: typing.Optional[RequestOptions] = None
     ) -> SourceConnectionJob:
         """
-        Cancel a running sync job for a source connection.
+        Request cancellation of a running sync job.
+
+        The job will be marked as CANCELLING and the sync workflow will stop at the
+        next checkpoint. Already-processed entities are retained.
 
-        This endpoint requests cancellation and marks the job as CANCELLING.
-        The workflow updates the final status to CANCELLED when it processes
-        the cancellation request.
+        **Note**: Cancellation is asynchronous. The job status will change to CANCELLED
+        once the workflow has fully stopped.
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection (UUID)
 
         job_id : str
+            Unique identifier of the sync job to cancel (UUID)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -428,20 +454,18 @@ class SourceConnectionsClient:
         Returns
         -------
         SourceConnectionJob
-            Successful Response
+            Job with cancellation status
 
         Examples
         --------
         from airweave import AirweaveSDK
 
         client = AirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
         client.source_connections.cancel_job(
-            source_connection_id="source_connection_id",
-            job_id="job_id",
+            source_connection_id="550e8400-e29b-41d4-a716-446655440000",
+            job_id="660e8400-e29b-41d4-a716-446655440001",
         )
         """
         _response = self._raw_client.cancel_job(source_connection_id, job_id, request_options=request_options)
@@ -472,7 +496,13 @@ class AsyncSourceConnectionsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> typing.List[SourceConnectionListItem]:
         """
-        List source connections with minimal fields for performance.
+        Retrieve all source connections for your organization.
+
+        Returns a lightweight list of source connections with essential fields for
+        display and navigation. Use the collection filter to see connections within
+        a specific collection.
+
+        For full connection details including sync history, use the GET /{id} endpoint.
 
         Parameters
         ----------
@@ -480,8 +510,10 @@ class AsyncSourceConnectionsClient:
             Filter by collection readable ID
 
         skip : typing.Optional[int]
+            Number of connections to skip for pagination
 
         limit : typing.Optional[int]
+            Maximum number of connections to return (1-1000)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -489,7 +521,7 @@ class AsyncSourceConnectionsClient:
         Returns
         -------
         typing.List[SourceConnectionListItem]
-            Successful Response
+            List of source connections
 
         Examples
         --------
@@ -498,8 +530,6 @@ class AsyncSourceConnectionsClient:
         from airweave import AsyncAirweaveSDK
 
         client = AsyncAirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
 
@@ -507,8 +537,8 @@ class AsyncSourceConnectionsClient:
         async def main() -> None:
             await client.source_connections.list(
                 collection="collection",
-                skip=1,
-                limit=1,
+                skip=0,
+                limit=100,
             )
 
 
@@ -534,45 +564,42 @@ class AsyncSourceConnectionsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> SourceConnection:
         """
-        Create a new source connection.
+        Create a new source connection to sync data from an external source.
 
-        The authentication configuration determines the flow:
-        - DirectAuthentication: Immediate creation with provided credentials
-        - OAuthBrowserAuthentication: Returns shell with authentication URL
-        - OAuthTokenAuthentication: Immediate creation with provided token
-        - AuthProviderAuthentication: Using external auth provider
+        The authentication method determines the creation flow:
 
-        BYOC (Bring Your Own Client) is detected when client_id and client_secret
-        are provided in OAuthBrowserAuthentication.
+        - **Direct**: Provide credentials (API key, token) directly. Connection is created immediately.
+        - **OAuth Browser**: Returns a connection with an `auth_url` to redirect users for authentication.
+        - **OAuth Token**: Provide an existing OAuth token. Connection is created immediately.
+        - **Auth Provider**: Use a pre-configured auth provider (e.g., Composio, Pipedream).
 
-        sync_immediately defaults:
-        - True for: direct, oauth_token, auth_provider
-        - False for: oauth_browser, oauth_byoc (these sync after authentication)
+        After successful authentication, data sync can begin automatically or on-demand.
 
         Parameters
         ----------
         short_name : str
-            Source identifier (e.g., 'slack', 'github')
+            Source type identifier (e.g., 'slack', 'github', 'notion')
 
         readable_collection_id : str
-            Collection readable ID
+            The readable ID of the collection to add this connection to
 
         name : typing.Optional[str]
-            Connection name (defaults to '{Source Name} Connection')
+            Display name for the connection. If not provided, defaults to '{Source Name} Connection'.
 
         description : typing.Optional[str]
-            Connection description
+            Optional description of what this connection is used for
 
         config : typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]]
-            Source-specific configuration
+            Source-specific configuration (e.g., repository name, filters)
 
         schedule : typing.Optional[ScheduleConfig]
+            Optional sync schedule configuration
 
         sync_immediately : typing.Optional[bool]
             Run initial sync after creation. Defaults to True for direct/token/auth_provider, False for OAuth browser/BYOC flows (which sync after authentication)
 
         authentication : typing.Optional[Authentication]
-            Authentication config (defaults to OAuth browser flow for OAuth sources)
+            Authentication configuration. Type is auto-detected from provided fields.
 
         redirect_url : typing.Optional[str]
             URL to redirect to after OAuth flow completes (only used for OAuth flows)
@@ -583,7 +610,7 @@ class AsyncSourceConnectionsClient:
         Returns
         -------
         SourceConnection
-            Successful Response
+            Created source connection
 
         Examples
         --------
@@ -592,16 +619,14 @@ class AsyncSourceConnectionsClient:
         from airweave import AsyncAirweaveSDK
 
         client = AsyncAirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
 
 
         async def main() -> None:
             await client.source_connections.create(
-                short_name="short_name",
-                readable_collection_id="readable_collection_id",
+                short_name="github",
+                readable_collection_id="customer-support-tickets-x7k9m",
             )
 
 
@@ -625,11 +650,18 @@ class AsyncSourceConnectionsClient:
         self, source_connection_id: str, *, request_options: typing.Optional[RequestOptions] = None
     ) -> SourceConnection:
         """
-        Get a source connection with optional depth expansion.
+        Retrieve details of a specific source connection.
+
+        Returns complete information about the connection including:
+        - Configuration settings
+        - Authentication status
+        - Sync schedule and history
+        - Entity statistics
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection (UUID)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -637,7 +669,7 @@ class AsyncSourceConnectionsClient:
         Returns
         -------
         SourceConnection
-            Successful Response
+            Source connection details
 
         Examples
         --------
@@ -646,15 +678,13 @@ class AsyncSourceConnectionsClient:
         from airweave import AsyncAirweaveSDK
 
         client = AsyncAirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
 
 
         async def main() -> None:
             await client.source_connections.get(
-                source_connection_id="source_connection_id",
+                source_connection_id="550e8400-e29b-41d4-a716-446655440000",
             )
 
 
@@ -667,11 +697,19 @@ class AsyncSourceConnectionsClient:
         self, source_connection_id: str, *, request_options: typing.Optional[RequestOptions] = None
     ) -> SourceConnection:
         """
-        Delete a source connection and all related data.
+        Permanently delete a source connection and all its synced data.
+
+        This operation:
+        - Removes all entities synced from this source from the vector database
+        - Cancels any scheduled or running sync jobs
+        - Deletes the connection configuration and credentials
+
+        **Warning**: This action cannot be undone. All synced data will be permanently deleted.
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection to delete (UUID)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -679,7 +717,7 @@ class AsyncSourceConnectionsClient:
         Returns
         -------
         SourceConnection
-            Successful Response
+            Deleted source connection
 
         Examples
         --------
@@ -688,15 +726,13 @@ class AsyncSourceConnectionsClient:
         from airweave import AsyncAirweaveSDK
 
         client = AsyncAirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
 
 
         async def main() -> None:
             await client.source_connections.delete(
-                source_connection_id="source_connection_id",
+                source_connection_id="550e8400-e29b-41d4-a716-446655440000",
             )
 
 
@@ -717,29 +753,35 @@ class AsyncSourceConnectionsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> SourceConnection:
         """
-        Update a source connection.
+        Update an existing source connection's configuration.
 
-        Updateable fields:
-        - name, description
-        - config_fields
-        - cron_schedule
-        - auth_fields (direct auth only)
+        You can modify:
+        - **Name and description**: Display information
+        - **Configuration**: Source-specific settings (e.g., repository name, filters)
+        - **Schedule**: Cron expression for automatic syncs
+        - **Authentication**: Update credentials (direct auth only)
+
+        Only include the fields you want to change; omitted fields retain their current values.
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection to update (UUID)
 
         name : typing.Optional[str]
+            Updated display name for the connection
 
         description : typing.Optional[str]
+            Updated description
 
         config : typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]]
-            Source-specific configuration
+            Updated source-specific configuration
 
         schedule : typing.Optional[ScheduleConfig]
+            Updated sync schedule configuration
 
         authentication : typing.Optional[Authentication]
-            Authentication config (defaults to OAuth browser flow for OAuth sources)
+            Updated authentication credentials (direct auth only)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -747,7 +789,7 @@ class AsyncSourceConnectionsClient:
         Returns
         -------
         SourceConnection
-            Successful Response
+            Updated source connection
 
         Examples
         --------
@@ -756,15 +798,13 @@ class AsyncSourceConnectionsClient:
         from airweave import AsyncAirweaveSDK
 
         client = AsyncAirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
 
 
         async def main() -> None:
             await client.source_connections.update(
-                source_connection_id="source_connection_id",
+                source_connection_id="550e8400-e29b-41d4-a716-446655440000",
             )
 
 
@@ -789,25 +829,22 @@ class AsyncSourceConnectionsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> SourceConnectionJob:
         """
-        Trigger a sync run for a source connection.
+        Trigger a data synchronization job for a source connection.
 
-        Runs are always executed through Temporal workflow engine.
+        Starts an asynchronous sync job that pulls the latest data from the connected
+        source. The job runs in the background and you can monitor its progress using
+        the jobs endpoint.
 
-        Args:
-            db: Database session
-            source_connection_id: ID of the source connection to run
-            ctx: API context with organization and user information
-            guard_rail: Guard rail service for usage limits
-            force_full_sync: If True, forces a full sync with orphaned entity cleanup
-                            for continuous syncs. Raises 400 error if used on
-                            non-continuous syncs (which are always full syncs).
+        For continuous sync connections, this performs an incremental sync by default.
+        Use `force_full_sync=true` to perform a complete re-sync of all data.
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection to sync (UUID)
 
         force_full_sync : typing.Optional[bool]
-            Force a full sync ignoring cursor data instead of waiting for the daily cleanup schedule. Only allowed for continuous syncs.
+            Force a full sync ignoring cursor data. Only applies to continuous sync connections. Non-continuous connections always perform full syncs.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -815,7 +852,7 @@ class AsyncSourceConnectionsClient:
         Returns
         -------
         SourceConnectionJob
-            Successful Response
+            Created sync job
 
         Examples
         --------
@@ -824,16 +861,14 @@ class AsyncSourceConnectionsClient:
         from airweave import AsyncAirweaveSDK
 
         client = AsyncAirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
 
 
         async def main() -> None:
             await client.source_connections.run(
-                source_connection_id="source_connection_id",
-                force_full_sync=True,
+                source_connection_id="550e8400-e29b-41d4-a716-446655440000",
+                force_full_sync=False,
             )
 
 
@@ -852,13 +887,26 @@ class AsyncSourceConnectionsClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> typing.List[SourceConnectionJob]:
         """
-        Get sync jobs for a source connection.
+        Retrieve the sync job history for a source connection.
+
+        Returns a list of sync jobs ordered by creation time (newest first). Each job
+        includes status, timing information, and entity counts.
+
+        Job statuses:
+        - **PENDING**: Job is queued and waiting to start
+        - **RUNNING**: Sync is actively pulling and processing data
+        - **COMPLETED**: Sync finished successfully
+        - **FAILED**: Sync encountered an error
+        - **CANCELLED**: Sync was manually cancelled
+        - **CANCELLING**: Cancellation has been requested
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection (UUID)
 
         limit : typing.Optional[int]
+            Maximum number of jobs to return (1-1000)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -866,7 +914,7 @@ class AsyncSourceConnectionsClient:
         Returns
         -------
         typing.List[SourceConnectionJob]
-            Successful Response
+            List of sync jobs
 
         Examples
         --------
@@ -875,16 +923,14 @@ class AsyncSourceConnectionsClient:
         from airweave import AsyncAirweaveSDK
 
         client = AsyncAirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
 
 
         async def main() -> None:
             await client.source_connections.get_source_connection_jobs(
-                source_connection_id="source_connection_id",
-                limit=1,
+                source_connection_id="550e8400-e29b-41d4-a716-446655440000",
+                limit=100,
             )
 
 
@@ -899,17 +945,21 @@ class AsyncSourceConnectionsClient:
         self, source_connection_id: str, job_id: str, *, request_options: typing.Optional[RequestOptions] = None
     ) -> SourceConnectionJob:
         """
-        Cancel a running sync job for a source connection.
+        Request cancellation of a running sync job.
+
+        The job will be marked as CANCELLING and the sync workflow will stop at the
+        next checkpoint. Already-processed entities are retained.
 
-        This endpoint requests cancellation and marks the job as CANCELLING.
-        The workflow updates the final status to CANCELLED when it processes
-        the cancellation request.
+        **Note**: Cancellation is asynchronous. The job status will change to CANCELLED
+        once the workflow has fully stopped.
 
         Parameters
         ----------
         source_connection_id : str
+            Unique identifier of the source connection (UUID)
 
         job_id : str
+            Unique identifier of the sync job to cancel (UUID)
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -917,7 +967,7 @@ class AsyncSourceConnectionsClient:
         Returns
         -------
         SourceConnectionJob
-            Successful Response
+            Job with cancellation status
 
         Examples
         --------
@@ -926,16 +976,14 @@ class AsyncSourceConnectionsClient:
         from airweave import AsyncAirweaveSDK
 
         client = AsyncAirweaveSDK(
-            framework_name="YOUR_FRAMEWORK_NAME",
-            framework_version="YOUR_FRAMEWORK_VERSION",
             api_key="YOUR_API_KEY",
         )
 
 
         async def main() -> None:
             await client.source_connections.cancel_job(
-                source_connection_id="source_connection_id",
-                job_id="job_id",
+                source_connection_id="550e8400-e29b-41d4-a716-446655440000",
+                job_id="660e8400-e29b-41d4-a716-446655440001",
             )