Restores

A Restore kicks off a process to restore deleted data for your Site. We are only able to restore deleted items up less than 365 days old. This is available to Site Administrators and to Workspace Administrators when the restore is scoped to their workspace.

This process does not validate the existence of prior files and folders at the creation time of the Restore. If a file or directory is incorrect, does not exist, or is older than 365 days, the restore process will still show to have completed successfully even if no items were restored.

While regular expressions and user-supplied wildcards are not supported, the system automatically applies a wildcard at the end of the prefix and is case-insensitive. Example: A prefix of test will match test1/, test2/, testing.txt, Testfile1.mp4, Testing.pdf, etc.

Restore types

Restore supports multiple restoration types, controlled by the restoration_type field:

  • files (default): Restore deleted files/folders (and optionally file permissions) by path prefix.
  • users: Restore deleted users (and optionally user permissions) by username prefix.

Restoring deleted files/folders (restoration_type=files)

  • To restore a specific file, specify the path to the file in the prefix field. Example: path/to/my/deleted_file.txt
  • To restore a directory, specify the directory path ending with an / in the prefix field. Example: path/to/my/deleted_directory/ This restores that folder and its contents without matching sibling names that begin with the same text.
  • To restore all deleted items, specify an empty string ('') in the prefix field or omit the field from the request. A workspace-scoped restore includes only that workspace.
  • With restore_deleted_permissions=true, an in-place restore also restores user and group permissions on folders returned by the restore and their subfolders, when those permissions were deleted within 24 hours after the folder's deletion, including both endpoints. Permissions removed before the folder was deleted or more than 24 hours afterward remain deleted. Permissions removed independently during that window are included.
  • If a folder already exists at the original path, restored content goes into it and eligible permissions apply to it. Permissions for deleted users or groups remain deleted. Restoring into a new restoration folder does not restore permissions.

Restoring deleted users (restoration_type=users)

  • Use earliest_date to select users deleted on or after that date/time. Restore all matching users by omitting prefix (or using '').
  • To restore specific deleted users by username, use prefix as a case-insensitive username prefix. Example: A prefix of john will match john, johnny, John.Doe, etc.
  • For each restored user, we also restore associated authentication and access records removed as part of deleting that user:
    • Permissions (when restore_deleted_permissions=true)
    • Two-factor authentication methods
    • SFTP/SSH keys
    • API keys
  • Records deleted independently of the user remain deleted, even if they were deleted after earliest_date.

List Restores

SDK Method

files_sdk.restore.list()

Return Object

ListObj[Restore]

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator or a Workspace Administrator for the relevant workspace.

Additional Arguments

Example Request

import files_sdk

try:
  restores = files_sdk.restore.list()
  for restore in restores.auto_paging_iter():
    # Operate on restore
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

Create Restore

SDK Method

files_sdk.restore.create()

Return Object

Restore

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator or a Workspace Administrator for the relevant workspace.

Method Arguments

ArgumentDefaultDescription
earliest_date
string
Required		Restore files or users deleted on or after this date/time. Don't set this earlier than you need. Can not be greater than 365 days prior to the restore request.
prefix
string		""Prefix of the files/folders to restore, or a case-insensitive username prefix for a user restore. A trailing slash selects that folder and its contents only; without it, the prefix matches any path beginning with that text. Do not use a leading slash. To restore all deleted items of the selected restoration type within the selected site or workspace scope, specify an empty string ('') or omit the field.
restoration_type
string		"files"Type of restoration to perform. files restores deleted filesystem items. users restores deleted users and associated access/authentication records removed as part of deleting those users.
Possible values: files, users
restore_deleted_permissions
boolean		trueIf true, a user restore restores permissions removed as part of deleting the selected users. An in-place file restore restores user and group permissions on returned folders and their subfolders that were deleted from the time of the folder's deletion through 24 hours afterward, including permissions removed independently within that window. File restores into a new folder do not restore permissions.
restore_in_place
boolean		trueIf true, we will restore the files in place (into their original paths). If false, we will create a new restoration folder in the root and restore files there.
update_timestamps
boolean		trueIf true, we will update the last modified timestamp of restored files to today's date. If false, we might trigger File Expiration to delete the file again.
workspace_id
int64		0Workspace ID for a workspace-scoped restore. 0 means the default site-wide scope.

Example Request

import files_sdk

try:
  restore = files_sdk.restore.create({
    "earliest_date": "2000-01-01T01:00:00Z"
  })
  # Operate on restore
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

The Restore Object

Some of the methods above return a Restore object. The attributes of this object are listed below.

AttributeDescription
earliest_date
date-time		Restore files or users deleted on or after this date/time. Don't set this earlier than you need. Can not be greater than 365 days prior to the restore request.
id
int64		Restore Record ID.
dirs_restored
int64		Number of directories that were successfully restored.
dirs_errored
int64		Number of directories that were not able to be restored.
dirs_total
int64		Total number of directories processed.
files_restored
int64		Number of files successfully restored.
files_errored
int64		Number of files that were not able to be restored.
files_total
int64		Total number of files processed.
prefix
string		Prefix of the files/folders to restore, or a case-insensitive username prefix for a user restore. A trailing slash selects that folder and its contents only; without it, the prefix matches any path beginning with that text. Do not use a leading slash. To restore all deleted items of the selected restoration type within the selected site or workspace scope, specify an empty string ('') or omit the field.
restoration_type
string		Type of restoration to perform. files restores deleted filesystem items. users restores deleted users and associated access/authentication records removed as part of deleting those users.
Possible values: files, users
restore_in_place
boolean		If true, we will restore the files in place (into their original paths). If false, we will create a new restoration folder in the root and restore files there.
restore_deleted_permissions
boolean		If true, a user restore restores permissions removed as part of deleting the selected users. An in-place file restore restores user and group permissions on returned folders and their subfolders that were deleted from the time of the folder's deletion through 24 hours afterward, including permissions removed independently within that window. File restores into a new folder do not restore permissions.
users_restored
int64		Number of users successfully restored (only present for restoration_type=users).
users_errored
int64		Number of users that failed to restore (only present for restoration_type=users).
users_total
int64		Total number of users processed (only present for restoration_type=users).
api_keys_restored
int64		Number of API keys restored (only present for restoration_type=users).
public_keys_restored
int64		Number of public keys restored (only present for restoration_type=users).
two_factor_authentication_methods_restored
int64		Number of two factor authentication methods restored (only present for restoration_type=users).
status
string		Status of the restoration process.
Possible values: pending, counting, restoring, complete, validating
update_timestamps
boolean		If true, we will update the last modified timestamp of restored files to today's date. If false, we might trigger File Expiration to delete the file again.
workspace_id
int64		Workspace ID for a workspace-scoped restore. 0 means the default site-wide scope.
error_messages
array(string)		Error messages received while restoring files and/or directories. Only present if there were errors.