As well as manually adding files to an assistant, you can synchronize files from an existing external source - such as a SharePoint library or content management system.

This guide walks you through creating and configuring a custom connector in Power Automate (or Power Apps/Logic Apps) using an OpenAPI definition, to do this.

The File Sync API supports various file operations—including uploads, deletions, change detection, and pruning obsolete files—to support the synchronization. 

File sync API setup and configuration

Download the OpenAPI definition

1. Locate the definition:
   Download the OpenAPI (Swagger) JSON file (e.g., file-sync.json) from the Integration tab for your assistant. This file provides the complete API description used to build the custom connector.

2. Key information:
   The OpenAPI document contains metadata such as:

   • Title: File Sync Connector
   • Version: 1.0.0
   • Description: Allows for file sync operations from an external source (e.g., SharePoint, CMS)
   • Security: Uses an API key via the header Api-Key

Create the custom connector

1. Navigate to Connector Creation:
   In Power Automate (or Power Apps), go to Data > Custom connectors and click + New custom connector.

2. Import the OpenAPI file:
   Select Import an OpenAPI file and upload the file-sync.json file you downloaded.

3. Connector details:

   • Name: Use a descriptive name such as “File Sync Connector.”
   • Description: For example, “Allows file sync operations from external sources (e.g. SharePoint, CMS, websites) including uploads, deletions, change detection, and pruning obsolete files.”

4. Reference documentation:
   For additional details, consult Microsoft’s documentation on Creating a custom connector from an OpenAPI definition.

Configure security (API Key)

Within the connector wizard’s Security tab:

• Security Type: Select API Key.
• Parameter Label: Api-Key
• Parameter Name: Api-Key (this must exactly match the OpenAPI spec)
• Location: Header

API endpoints overview

The OpenAPI specification defines several endpoints, each designed for specific file sync scenarios:

1. File Upload Operations

Multipart/Form-Data Upload

• Endpoint:
  POST /api/assistants/{assistantId}/files/sync

• Description:
  Uploads a file from an external source using a multipart/form-data request. The file’s name is automatically extracted from the file metadata.

• Request Body Parameters:

  • file (required): Binary file content.
  • fileSourceUrl (optional): URL of the original file (e.g., a SharePoint link).
  • sourceUid (required): A unique identifier to prevent filename collisions and specify the external source.
  • fileSourceUid (optional): Used to uniquely identify files in hierarchical sources (if omitted, the file’s name is used).
  • fileSourceHash (optional): Hash of the source file for change detection.

JSON Payload Upload

• Endpoint:
  POST /api/assistants/{assistantId}/files/sync/json

• Description:
  Uploads a file using a JSON payload. This method requires an explicit file name.

• Request Body Parameters:

  • sourceUid (required): Unique identifier for the external source.
  • fileName (required): Explicit name for the file.
  • data (required): Base64 encoded file content.
  • fileSourceUrl (optional): URL pointing to the file’s original location.
  • fileSourceUid (optional): Uniquely identifies the file within hierarchical sources.
  • fileSourceHash (optional): Used for change detection.

2. File Deletion

• Endpoint:
  POST /api/assistants/{assistantId}/files/sync/delete

• Description:
  Deletes a previously synced file from your assistant service. The file is identified by either the fileName or the fileSourceUid (if provided during upload).

• Request Body:
  The request uses a JSON payload (defined by the FileSyncDeleteRequest schema) that includes:

  • assistantId
  • sourceUid
  • fileName or fileSourceUid

3. Change Detection

• Endpoint:
  GET /api/assistants/{assistantId}/files/sync/file-has-changed

• Description:
  Determines whether the file has changed by comparing the provided fileSourceHash with the current hash of the file stored in your assistant service.

• Query Parameters:

  • sourceUid (required): Unique identifier for the external source.
  • fileName (required): Name of the file to check.
  • fileSourceUid (optional): Used for hierarchical file systems.
  • fileSourceHash (required): The hash value for change detection.

• Response:
  Returns a JSON object (FileChangeResult) indicating if the file exists and whether it has changed.

4. Prune Obsolete Files

• Endpoint:
  POST /api/assistants/{assistantId}/files/sync/prune-obsolete-files

• Description:
  Removes files that are no longer present in the external source. You must supply an array of file references (each containing a fileName and optionally a fileSourceUid) representing the current set of files.

• Query Parameter:

  • sourceUid (required): Unique identifier for the external source.

• Request Body:
  A JSON array of file references.

5. Retrieve File Sync Operations

• Endpoint:
  GET /api/assistants/{assistantId}/files/sync/operations

• Description:
  Retrieves a paginated list of file sync operations. This endpoint allows you to filter operations by date range, operation type, and status.

• Query Parameters:

  • startDateUtc (optional): ISO 8601 UTC start date filter.
  • endDateUtc (optional): ISO 8601 UTC end date filter.
  • operationType (optional): Filter by type (e.g., Upload, Delete).
  • status (optional): Filter by status (e.g., Pending, Processing, CompletedSuccess, CompletedFailed, CompletedSkipped).
  • page (required): 1-based page number.
  • perPage (required): Number of items per page.

Use cases and scenarios

Real-time synchronization (e.g., SharePoint)

• File Uploads:
  Use the multipart or JSON upload endpoints to immediately sync files as events occur.
• File Deletions:
  React promptly to deletion events using the deletion endpoint.
• Advantage:
  In environments like SharePoint, change detection and obsolete file pruning are less critical because file events are pushed in real time.

Periodic syncs for non-event-based sources

• Scheduled uploads:
  Set up periodic synchronizations using the provided upload methods.
• Change detection:
  Verify file modifications with the change detection endpoint.
• Pruning:
  Use the prune obsolete files endpoint to remove files that are no longer present in the external source.

Testing the Connector

1. Establish a connection:
   In the Test tab of your connector in Power Automate (or Power Apps), create a new connection using your Api-Key.

2. Test each operation:

   • File upload:
     Test both the multipart/form-data and JSON upload endpoints.
   • File deletion:
     Verify deletion operations using the /delete endpoint.
   • Change detection:
     Check if file changes are correctly detected.
   • Prune obsolete files:
     Confirm that files missing from the current sync are removed.
   • Operations retrieval:
     Use the operations endpoint to monitor file sync activities.

---

File size considerations

• UI Limit: The maximum file size through the UI is currently 250MB.
• API: The maximum file size through the API is 100MB.

OpenAPI Document Overview

The provided OpenAPI document includes:

• Metadata:
  Title, version, description, terms of service, and contact information.

• Servers:
  A placeholder server URL (https://{baseUrl}) that tenants replace with their own domain.

• Security:
  An API key scheme defined via the Api-Key header.

• Path Definitions:
  Detailed endpoint descriptions and operations for file uploads, deletion, change detection, pruning obsolete files, and retrieving operations.

• Schemas:
  Definitions for request and response models, including file references, operation details, and error responses.

Conclusion

By following this guide, you can successfully set up and configure the File Sync API custom connector in Power Automate, Power Apps, or Logic Apps. This enables seamless file synchronization between external sources—whether they push real-time events or require periodic syncs—and your assistant service.

For further details and advanced configuration, please refer to Microsoft’s official documentation on creating custom connectors using an OpenAPI definition.