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

restore.List()

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.

Additional Arguments

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/restore"
)

restoreIterator, err := restore.List(files_sdk.RestoreListParams{})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

for restoreIterator.Next() {
    restore := restoreIterator.restore()
}
err = restoreIterator.Err()
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

Create Restore

SDK Method

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.

RestoreCreateParams Fields

FieldDefaultDescription
EarliestDate
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.
RestorationType
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
RestoreDeletedPermissions
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.
RestoreInPlace
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.
UpdateTimestamps
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.
WorkspaceId
int64		0Workspace ID for a workspace-scoped restore. 0 means the default site-wide scope.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    "github.com/Files-com/files-sdk-go/v3/restore"
)

restore, err := restore.Create(files_sdk.RestoreCreateParams{EarliestDate: "2000-01-01T01:00:00Z"})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Println("Response Error Occurred (" + respErr.Type + "): " + respErr.ErrorMessage)
    } else {
        fmt.Printf("Unexpected Error: %s\n", err.Error())
    }
}

The Restore Object

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

AttributeDescription
EarliestDate
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.
DirsRestored
int64		Number of directories that were successfully restored.
DirsErrored
int64		Number of directories that were not able to be restored.
DirsTotal
int64		Total number of directories processed.
FilesRestored
int64		Number of files successfully restored.
FilesErrored
int64		Number of files that were not able to be restored.
FilesTotal
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.
RestorationType
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
RestoreInPlace
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.
RestoreDeletedPermissions
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.
UsersRestored
int64		Number of users successfully restored (only present for restoration_type=users).
UsersErrored
int64		Number of users that failed to restore (only present for restoration_type=users).
UsersTotal
int64		Total number of users processed (only present for restoration_type=users).
ApiKeysRestored
int64		Number of API keys restored (only present for restoration_type=users).
PublicKeysRestored
int64		Number of public keys restored (only present for restoration_type=users).
TwoFactorAuthenticationMethodsRestored
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
UpdateTimestamps
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.
WorkspaceId
int64		Workspace ID for a workspace-scoped restore. 0 means the default site-wide scope.
ErrorMessages
array(string)		Error messages received while restoring files and/or directories. Only present if there were errors.