Syncs

A Sync represents a file synchronization job between two locations (local-remote, remote-remote, local-child_site, etc). It can be scheduled, run manually, or triggered by custom logic. Syncs track their runs, status, and configuration.

List Syncs

Endpoint

GET/syncs

Return Object

Sync[]

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Additional Arguments

Example Request

curl https://app.files.com/api/rest/v1/syncs.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

[
  {
    "id": 1,
    "name": "example",
    "description": "example",
    "site_id": 1,
    "workspace_id": 1,
    "user_id": 1,
    "src_path": "example",
    "dest_path": "example",
    "src_remote_server_id": 1,
    "dest_remote_server_id": 1,
    "src_site_id": 1,
    "dest_site_id": 1,
    "two_way": true,
    "keep_after_copy": true,
    "delete_empty_folders": true,
    "disabled": true,
    "trigger": "example",
    "trigger_file": "example",
    "always_write_trigger_file": true,
    "include_patterns": [
      "example"
    ],
    "exclude_patterns": [
      "example"
    ],
    "created_at": "2000-01-01T01:00:00Z",
    "updated_at": "2000-01-01T01:00:00Z",
    "sync_interval_minutes": 1,
    "interval": "week",
    "recurring_day": 25,
    "recurring_days": [
      1,
      15
    ],
    "schedule_id": 1,
    "schedule_days_of_week": [
      0,
      2,
      4
    ],
    "schedule_times_of_day": [
      "06:30",
      "14:30"
    ],
    "schedule_time_zone": "Eastern Time (US & Canada)",
    "holiday_region": "us_dc",
    "latest_sync_run": {
      "id": 1,
      "body": "example",
      "bytes_synced": 1,
      "compared_files": 1,
      "compared_folders": 1,
      "completed_at": "2000-01-01T01:00:00Z",
      "created_at": "2000-01-01T01:00:00Z",
      "dest_remote_server_type": "example",
      "dry_run": true,
      "errored_files": 1,
      "estimated_bytes_count": 1,
      "event_errors": [
        "example"
      ],
      "log_url": "https://www.example.com/log_file.txt",
      "runtime": 1.0,
      "site_id": 1,
      "workspace_id": 1,
      "src_remote_server_type": "example",
      "status": "example",
      "successful_files": 1,
      "sync_id": 1,
      "sync_name": "Azure to SharePoint Sync",
      "updated_at": "2000-01-01T01:00:00Z",
      "live_transfers": [
        {
          "path": "example",
          "status": "example",
          "bytes_copied": 1,
          "bytes_total": 1,
          "percentage": 1.0,
          "eta": "example",
          "started_at": "example"
        }
      ]
    }
  }
]

Show Sync

Endpoint

GET/syncs/{id}

Return Object

Sync

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Sync ID.

Example Request

curl https://app.files.com/api/rest/v1/syncs/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "name": "example",
  "description": "example",
  "site_id": 1,
  "workspace_id": 1,
  "user_id": 1,
  "src_path": "example",
  "dest_path": "example",
  "src_remote_server_id": 1,
  "dest_remote_server_id": 1,
  "src_site_id": 1,
  "dest_site_id": 1,
  "two_way": true,
  "keep_after_copy": true,
  "delete_empty_folders": true,
  "disabled": true,
  "trigger": "example",
  "trigger_file": "example",
  "always_write_trigger_file": true,
  "include_patterns": [
    "example"
  ],
  "exclude_patterns": [
    "example"
  ],
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z",
  "sync_interval_minutes": 1,
  "interval": "week",
  "recurring_day": 25,
  "recurring_days": [
    1,
    15
  ],
  "schedule_id": 1,
  "schedule_days_of_week": [
    0,
    2,
    4
  ],
  "schedule_times_of_day": [
    "06:30",
    "14:30"
  ],
  "schedule_time_zone": "Eastern Time (US & Canada)",
  "holiday_region": "us_dc",
  "latest_sync_run": {
    "id": 1,
    "body": "example",
    "bytes_synced": 1,
    "compared_files": 1,
    "compared_folders": 1,
    "completed_at": "2000-01-01T01:00:00Z",
    "created_at": "2000-01-01T01:00:00Z",
    "dest_remote_server_type": "example",
    "dry_run": true,
    "errored_files": 1,
    "estimated_bytes_count": 1,
    "event_errors": [
      "example"
    ],
    "log_url": "https://www.example.com/log_file.txt",
    "runtime": 1.0,
    "site_id": 1,
    "workspace_id": 1,
    "src_remote_server_type": "example",
    "status": "example",
    "successful_files": 1,
    "sync_id": 1,
    "sync_name": "Azure to SharePoint Sync",
    "updated_at": "2000-01-01T01:00:00Z",
    "live_transfers": [
      {
        "path": "example",
        "status": "example",
        "bytes_copied": 1,
        "bytes_total": 1,
        "percentage": 1.0,
        "eta": "example",
        "started_at": "example"
      }
    ]
  }
}

Create Sync

Endpoint

POST/syncs

Return Object

Sync

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Default	Description
delete_empty_folders boolean	`false`	Delete empty folders after sync?
description string		Description for this sync job
dest_path string	`""`	Absolute destination path for the sync
dest_remote_server_id int64		Remote server ID for the destination (if remote)
disabled boolean	`false`	Is this sync disabled?
exclude_patterns array(string)		Array of glob patterns to exclude
holiday_region string		Skip the sync if there is a formal, observed holiday for this region.
include_patterns array(string)		Array of glob patterns to include
interval string		If trigger is `daily`, this specifies how often to run this sync. One of: `day`, `week`, `week_end`, `month`, `month_end`, `quarter`, `quarter_end`, `year`, `year_end`
keep_after_copy boolean	`true`	Keep files after copying?
name string		Name for this sync job
recurring_day int64		If trigger type is `daily`, this specifies a day number to run in one of the supported intervals: `week`, `month`, `quarter`, `year`.
recurring_days array(int64)		If trigger type is `daily`, this specifies one or more day numbers to run in one of the supported intervals: `week`, `month`, `quarter`, `year`.
schedule_id int64		If trigger is `custom_schedule`, the reusable Schedule used instead of the sync's schedule fields.
schedule_days_of_week array(int64)		If trigger is `custom_schedule`, Custom schedule description for when the sync should be run. 0-based days of the week. 0 is Sunday, 1 is Monday, etc.
schedule_time_zone string		Time zone for the schedule. If not set, times are interpreted as UTC.
schedule_times_of_day array(string)		Times of day to run in HH:MM format. For `custom_schedule`, run at these times on specified days of week. For `daily`, run at these times on the scheduled interval date.
src_path string	`""`	Absolute source path for the sync
src_remote_server_id int64		Remote server ID for the source (if remote)
sync_interval_minutes int64		Frequency in minutes between syncs. If set, this value must be greater than or equal to the `remote_sync_interval` value for the site's plan. If left blank, the plan's `remote_sync_interval` will be used. This setting is only used if `trigger` is empty.
trigger string		Trigger type: daily, custom_schedule, or manual Possible values: `daily`, `custom_schedule`, `manual`
trigger_file string		Some MFT services request an empty file (known as a trigger file) to signal the sync is complete and they can begin further processing. If trigger_file is set, a zero-byte file will be sent at the end of the sync.
always_write_trigger_file boolean	`false`	If true, the trigger file will be sent at the end of a successful sync even when no files were transferred.
workspace_id int64	`0`	Workspace ID this sync belongs to

Example Request

curl https://app.files.com/api/rest/v1/syncs.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"delete_empty_folders":true,"description":"example","dest_path":"example","dest_remote_server_id":1,"disabled":true,"exclude_patterns":["example"],"holiday_region":"us_dc","include_patterns":["example"],"interval":"week","keep_after_copy":true,"name":"example","recurring_day":25,"recurring_days":[1,15],"schedule_id":1,"schedule_days_of_week":[0,2,4],"schedule_time_zone":"Eastern Time (US & Canada)","schedule_times_of_day":["06:30","14:30"],"src_path":"example","src_remote_server_id":1,"sync_interval_minutes":1,"trigger":"example","trigger_file":"example","always_write_trigger_file":true,"workspace_id":1}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "name": "example",
  "description": "example",
  "site_id": 1,
  "workspace_id": 1,
  "user_id": 1,
  "src_path": "example",
  "dest_path": "example",
  "src_remote_server_id": 1,
  "dest_remote_server_id": 1,
  "src_site_id": 1,
  "dest_site_id": 1,
  "two_way": true,
  "keep_after_copy": true,
  "delete_empty_folders": true,
  "disabled": true,
  "trigger": "example",
  "trigger_file": "example",
  "always_write_trigger_file": true,
  "include_patterns": [
    "example"
  ],
  "exclude_patterns": [
    "example"
  ],
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z",
  "sync_interval_minutes": 1,
  "interval": "week",
  "recurring_day": 25,
  "recurring_days": [
    1,
    15
  ],
  "schedule_id": 1,
  "schedule_days_of_week": [
    0,
    2,
    4
  ],
  "schedule_times_of_day": [
    "06:30",
    "14:30"
  ],
  "schedule_time_zone": "Eastern Time (US & Canada)",
  "holiday_region": "us_dc",
  "latest_sync_run": {
    "id": 1,
    "body": "example",
    "bytes_synced": 1,
    "compared_files": 1,
    "compared_folders": 1,
    "completed_at": "2000-01-01T01:00:00Z",
    "created_at": "2000-01-01T01:00:00Z",
    "dest_remote_server_type": "example",
    "dry_run": true,
    "errored_files": 1,
    "estimated_bytes_count": 1,
    "event_errors": [
      "example"
    ],
    "log_url": "https://www.example.com/log_file.txt",
    "runtime": 1.0,
    "site_id": 1,
    "workspace_id": 1,
    "src_remote_server_type": "example",
    "status": "example",
    "successful_files": 1,
    "sync_id": 1,
    "sync_name": "Azure to SharePoint Sync",
    "updated_at": "2000-01-01T01:00:00Z",
    "live_transfers": [
      {
        "path": "example",
        "status": "example",
        "bytes_copied": 1,
        "bytes_total": 1,
        "percentage": 1.0,
        "eta": "example",
        "started_at": "example"
      }
    ]
  }
}

Dry Run Sync

Endpoint

POST/syncs/{id}/dry_run

Return Object

No return value.

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Sync ID.

Example Request

curl https://app.files.com/api/rest/v1/syncs/{id}/dry_run.json \
  -X POST \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Manually Run Sync

Endpoint

POST/syncs/{id}/manual_run

Return Object

No return value.

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Sync ID.

Example Request

curl https://app.files.com/api/rest/v1/syncs/{id}/manual_run.json \
  -X POST \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Update Sync

Endpoint

PATCH/syncs/{id}

Return Object

Sync

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Sync ID.
delete_empty_folders boolean	Delete empty folders after sync?
description string	Description for this sync job
dest_path string	Absolute destination path for the sync
dest_remote_server_id int64	Remote server ID for the destination (if remote)
disabled boolean	Is this sync disabled?
exclude_patterns array(string)	Array of glob patterns to exclude
holiday_region string	Skip the sync if there is a formal, observed holiday for this region.
include_patterns array(string)	Array of glob patterns to include
interval string	If trigger is `daily`, this specifies how often to run this sync. One of: `day`, `week`, `week_end`, `month`, `month_end`, `quarter`, `quarter_end`, `year`, `year_end`
keep_after_copy boolean	Keep files after copying?
name string	Name for this sync job
recurring_day int64	If trigger type is `daily`, this specifies a day number to run in one of the supported intervals: `week`, `month`, `quarter`, `year`.
recurring_days array(int64)	If trigger type is `daily`, this specifies one or more day numbers to run in one of the supported intervals: `week`, `month`, `quarter`, `year`.
schedule_id int64	If trigger is `custom_schedule`, the reusable Schedule used instead of the sync's schedule fields.
schedule_days_of_week array(int64)	If trigger is `custom_schedule`, Custom schedule description for when the sync should be run. 0-based days of the week. 0 is Sunday, 1 is Monday, etc.
schedule_time_zone string	Time zone for the schedule. If not set, times are interpreted as UTC.
schedule_times_of_day array(string)	Times of day to run in HH:MM format. For `custom_schedule`, run at these times on specified days of week. For `daily`, run at these times on the scheduled interval date.
src_path string	Absolute source path for the sync
src_remote_server_id int64	Remote server ID for the source (if remote)
sync_interval_minutes int64	Frequency in minutes between syncs. If set, this value must be greater than or equal to the `remote_sync_interval` value for the site's plan. If left blank, the plan's `remote_sync_interval` will be used. This setting is only used if `trigger` is empty.
trigger string	Trigger type: daily, custom_schedule, or manual Possible values: `daily`, `custom_schedule`, `manual`
trigger_file string	Some MFT services request an empty file (known as a trigger file) to signal the sync is complete and they can begin further processing. If trigger_file is set, a zero-byte file will be sent at the end of the sync.
always_write_trigger_file boolean	If true, the trigger file will be sent at the end of a successful sync even when no files were transferred.

Example Request

curl https://app.files.com/api/rest/v1/syncs/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"delete_empty_folders":true,"description":"example","dest_path":"example","dest_remote_server_id":1,"disabled":true,"exclude_patterns":["example"],"holiday_region":"us_dc","include_patterns":["example"],"interval":"week","keep_after_copy":true,"name":"example","recurring_day":25,"recurring_days":[1,15],"schedule_id":1,"schedule_days_of_week":[0,2,4],"schedule_time_zone":"Eastern Time (US & Canada)","schedule_times_of_day":["06:30","14:30"],"src_path":"example","src_remote_server_id":1,"sync_interval_minutes":1,"trigger":"example","trigger_file":"example","always_write_trigger_file":true}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "name": "example",
  "description": "example",
  "site_id": 1,
  "workspace_id": 1,
  "user_id": 1,
  "src_path": "example",
  "dest_path": "example",
  "src_remote_server_id": 1,
  "dest_remote_server_id": 1,
  "src_site_id": 1,
  "dest_site_id": 1,
  "two_way": true,
  "keep_after_copy": true,
  "delete_empty_folders": true,
  "disabled": true,
  "trigger": "example",
  "trigger_file": "example",
  "always_write_trigger_file": true,
  "include_patterns": [
    "example"
  ],
  "exclude_patterns": [
    "example"
  ],
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z",
  "sync_interval_minutes": 1,
  "interval": "week",
  "recurring_day": 25,
  "recurring_days": [
    1,
    15
  ],
  "schedule_id": 1,
  "schedule_days_of_week": [
    0,
    2,
    4
  ],
  "schedule_times_of_day": [
    "06:30",
    "14:30"
  ],
  "schedule_time_zone": "Eastern Time (US & Canada)",
  "holiday_region": "us_dc",
  "latest_sync_run": {
    "id": 1,
    "body": "example",
    "bytes_synced": 1,
    "compared_files": 1,
    "compared_folders": 1,
    "completed_at": "2000-01-01T01:00:00Z",
    "created_at": "2000-01-01T01:00:00Z",
    "dest_remote_server_type": "example",
    "dry_run": true,
    "errored_files": 1,
    "estimated_bytes_count": 1,
    "event_errors": [
      "example"
    ],
    "log_url": "https://www.example.com/log_file.txt",
    "runtime": 1.0,
    "site_id": 1,
    "workspace_id": 1,
    "src_remote_server_type": "example",
    "status": "example",
    "successful_files": 1,
    "sync_id": 1,
    "sync_name": "Azure to SharePoint Sync",
    "updated_at": "2000-01-01T01:00:00Z",
    "live_transfers": [
      {
        "path": "example",
        "status": "example",
        "bytes_copied": 1,
        "bytes_total": 1,
        "percentage": 1.0,
        "eta": "example",
        "started_at": "example"
      }
    ]
  }
}

Delete Sync

Endpoint

DELETE/syncs/{id}

Return Object

No return value.

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

Parameter	Description
id int64 Required	Sync ID.

Example Request

curl https://app.files.com/api/rest/v1/syncs/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

The Sync Object

Some of the endpoints above return a Sync object. The attributes of this object are listed below.

Attribute	Description
id int64	Sync ID
name string	Name for this sync job
description string	Description for this sync job
site_id int64	Site ID this sync belongs to
workspace_id int64	Workspace ID this sync belongs to
user_id int64	User who created or owns this sync
src_path string	Absolute source path for the sync
dest_path string	Absolute destination path for the sync
src_remote_server_id int64	Remote server ID for the source (if remote)
dest_remote_server_id int64	Remote server ID for the destination (if remote)
src_site_id int64	Source site ID if syncing from a child or partner site
dest_site_id int64	Destination site ID if syncing to a child or partner site
two_way boolean	Is this a two-way sync?
keep_after_copy boolean	Keep files after copying?
delete_empty_folders boolean	Delete empty folders after sync?
disabled boolean	Is this sync disabled?
trigger string	Trigger type: daily, custom_schedule, or manual Possible values: `daily`, `custom_schedule`, `manual`
trigger_file string	Some MFT services request an empty file (known as a trigger file) to signal the sync is complete and they can begin further processing. If trigger_file is set, a zero-byte file will be sent at the end of the sync.
always_write_trigger_file boolean	If true, the trigger file will be sent at the end of a successful sync even when no files were transferred.
include_patterns array(string)	Array of glob patterns to include
exclude_patterns array(string)	Array of glob patterns to exclude
created_at date-time	When this sync was created
updated_at date-time	When this sync was last updated
sync_interval_minutes int64	Frequency in minutes between syncs. If set, this value must be greater than or equal to the `remote_sync_interval` value for the site's plan. If left blank, the plan's `remote_sync_interval` will be used. This setting is only used if `trigger` is empty.
interval string	If trigger is `daily`, this specifies how often to run this sync. One of: `day`, `week`, `week_end`, `month`, `month_end`, `quarter`, `quarter_end`, `year`, `year_end`
recurring_day int64	If trigger type is `daily`, this specifies a day number to run in one of the supported intervals: `week`, `month`, `quarter`, `year`.
recurring_days array(int64)	If trigger type is `daily`, this specifies one or more day numbers to run in one of the supported intervals: `week`, `month`, `quarter`, `year`.
schedule_id int64	If trigger is `custom_schedule`, the reusable Schedule used instead of the sync's schedule fields.
schedule_days_of_week array(int64)	If trigger is `custom_schedule`, Custom schedule description for when the sync should be run. 0-based days of the week. 0 is Sunday, 1 is Monday, etc.
schedule_times_of_day array(string)	Times of day to run in HH:MM format. For `custom_schedule`, run at these times on specified days of week. For `daily`, run at these times on the scheduled interval date.
schedule_time_zone string	Time zone for the schedule. If not set, times are interpreted as UTC.
holiday_region string	Skip the sync if there is a formal, observed holiday for this region.
latest_sync_run SyncRun	The latest run of this sync

Example Sync Object

{
  "id": 1,
  "name": "example",
  "description": "example",
  "site_id": 1,
  "workspace_id": 1,
  "user_id": 1,
  "src_path": "example",
  "dest_path": "example",
  "src_remote_server_id": 1,
  "dest_remote_server_id": 1,
  "src_site_id": 1,
  "dest_site_id": 1,
  "two_way": true,
  "keep_after_copy": true,
  "delete_empty_folders": true,
  "disabled": true,
  "trigger": "example",
  "trigger_file": "example",
  "always_write_trigger_file": true,
  "include_patterns": [
    "example"
  ],
  "exclude_patterns": [
    "example"
  ],
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z",
  "sync_interval_minutes": 1,
  "interval": "week",
  "recurring_day": 25,
  "recurring_days": [
    1,
    15
  ],
  "schedule_id": 1,
  "schedule_days_of_week": [
    0,
    2,
    4
  ],
  "schedule_times_of_day": [
    "06:30",
    "14:30"
  ],
  "schedule_time_zone": "Eastern Time (US & Canada)",
  "holiday_region": "us_dc",
  "latest_sync_run": {
    "id": 1,
    "body": "example",
    "bytes_synced": 1,
    "compared_files": 1,
    "compared_folders": 1,
    "completed_at": "2000-01-01T01:00:00Z",
    "created_at": "2000-01-01T01:00:00Z",
    "dest_remote_server_type": "example",
    "dry_run": true,
    "errored_files": 1,
    "estimated_bytes_count": 1,
    "event_errors": [
      "example"
    ],
    "log_url": "https://www.example.com/log_file.txt",
    "runtime": 1.0,
    "site_id": 1,
    "workspace_id": 1,
    "src_remote_server_type": "example",
    "status": "example",
    "successful_files": 1,
    "sync_id": 1,
    "sync_name": "Azure to SharePoint Sync",
    "updated_at": "2000-01-01T01:00:00Z",
    "live_transfers": [
      {
        "path": "example",
        "status": "example",
        "bytes_copied": 1,
        "bytes_total": 1,
        "percentage": 1.0,
        "eta": "example",
        "started_at": "example"
      }
    ]
  }
}

Syncs

Endpoint

Return Object

Authorization Requirement

Additional Arguments

Pagination

Sorting

Filtering

Endpoint

Return Object

Authorization Requirement

Request Parameters

Endpoint

Return Object

Authorization Requirement

Request Parameters

Endpoint

Return Object

Authorization Requirement

Request Parameters

Endpoint

Return Object

Authorization Requirement

Request Parameters

Endpoint

Return Object

Authorization Requirement

Request Parameters

Endpoint

Return Object

Authorization Requirement

Request Parameters