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/
  • To restore all deleted items, specify an empty string ('') in the prefix field or omit the field from the request.

Restoring deleted users (restoration_type=users)

  • Restore all deleted users since earliest_date 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.
  • When restoring users, we also restore associated authentication and access records deleted since earliest_date, including:
    • Permissions (when restore_deleted_permissions=true)
    • Two-factor authentication methods
    • Public keys
    • API keys

List Restores

Endpoint

GET/restores

Return Object

Restore[]

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/restores.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

[
  {
    "earliest_date": "2000-01-01T01:00:00Z",
    "id": 1,
    "dirs_restored": 1,
    "dirs_errored": 1,
    "dirs_total": 1,
    "files_restored": 1,
    "files_errored": 1,
    "files_total": 1,
    "prefix": "foo/bar/baz.txt",
    "restoration_type": "files",
    "restore_in_place": true,
    "restore_deleted_permissions": true,
    "users_restored": 1,
    "users_errored": 1,
    "users_total": 1,
    "api_keys_restored": 1,
    "public_keys_restored": 1,
    "two_factor_authentication_methods_restored": 1,
    "status": "pending",
    "update_timestamps": true,
    "workspace_id": 12,
    "error_messages": [
      "example"
    ]
  }
]

Create Restore

Endpoint

POST/restores

Return Object

Restore

Authorization Requirement

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

Request Parameters

ParameterDefaultDescription
earliest_date
string
Required		Restore all files deleted 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. To restore a folder, add a trailing slash to the folder name. Do not use a leading slash. To restore all deleted items, specify an empty string ('') in the prefix field or omit the field from the request.
restoration_type
string		"files"Type of restoration to perform. files restores deleted filesystem items. users restores deleted users and associated access/authentication records.
Possible values: files, users
restore_deleted_permissions
boolean		trueIf true, we will also restore any Permissions that match the same path prefix from the same dates.
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

curl https://app.files.com/api/rest/v1/restores.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"earliest_date":"2000-01-01T01:00:00Z","prefix":"foo/bar/baz.txt","restoration_type":"files","restore_deleted_permissions":true,"restore_in_place":true,"update_timestamps":true,"workspace_id":12}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "earliest_date": "2000-01-01T01:00:00Z",
  "id": 1,
  "dirs_restored": 1,
  "dirs_errored": 1,
  "dirs_total": 1,
  "files_restored": 1,
  "files_errored": 1,
  "files_total": 1,
  "prefix": "foo/bar/baz.txt",
  "restoration_type": "files",
  "restore_in_place": true,
  "restore_deleted_permissions": true,
  "users_restored": 1,
  "users_errored": 1,
  "users_total": 1,
  "api_keys_restored": 1,
  "public_keys_restored": 1,
  "two_factor_authentication_methods_restored": 1,
  "status": "pending",
  "update_timestamps": true,
  "workspace_id": 12,
  "error_messages": [
    "example"
  ]
}

The Restore Object

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

AttributeDescription
earliest_date
date-time		Restore all files deleted 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. To restore a folder, add a trailing slash to the folder name. Do not use a leading slash. To restore all deleted items, specify an empty string ('') in the prefix field or omit the field from the request.
restoration_type
string		Type of restoration to perform. files restores deleted filesystem items. users restores deleted users and associated access/authentication records.
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, we will also restore any Permissions that match the same path prefix from the same dates.
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.

Example Restore Object

{
  "earliest_date": "2000-01-01T01:00:00Z",
  "id": 1,
  "dirs_restored": 1,
  "dirs_errored": 1,
  "dirs_total": 1,
  "files_restored": 1,
  "files_errored": 1,
  "files_total": 1,
  "prefix": "foo/bar/baz.txt",
  "restoration_type": "files",
  "restore_in_place": true,
  "restore_deleted_permissions": true,
  "users_restored": 1,
  "users_errored": 1,
  "users_total": 1,
  "api_keys_restored": 1,
  "public_keys_restored": 1,
  "two_factor_authentication_methods_restored": 1,
  "status": "pending",
  "update_timestamps": true,
  "workspace_id": 12,
  "error_messages": [
    "example"
  ]
}