Files

The File and Folder resources allow you to operate on files and folders. While the two resources are similar, they are not exactly the same, so pay close attention to the documentation to ensure that you are operating on the correct resource for the operation you are trying to perform.

Download File

SDK Method

file.download();

Return Object

File

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
path
string
Required		Path to operate on.

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  const remoteFile = await new File({ path: path }).download();
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Download to File/Stream/String

SDK Method

file.downloadToFile()

Return Object

No return value.

Method Arguments

ArgumentDescription
destinationPath
string
Required		Local path to download the file to.

SDK Method

file.downloadToStream()

Return Object

No return value.

Method Arguments

ArgumentDescription
writableStream
WritableStream
Required		Writable stream to download the file to.

SDK Method

file.downloadToString()

Return Object

string

Example Requests (not available in browser)

import { isBrowser } from 'files.com/lib/utils';
import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  const remoteFile = await new File({ path: path }).download();
  
  if (!isBrowser()) {
    // download to a file on disk
    await remoteFile.downloadToFile(destinationPath);
  
    // download to a writable stream
    await remoteFile.downloadToStream(writableStream);
  
    // download in memory and return as a UTF-8 string
    const textContent = await remoteFile.downloadToString();
  }
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Upload File

SDK Method

File.uploadData()

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
destinationPath
string
Required		Remote path to upload the file/folder to.
data
any
Required		Raw file data to upload.
params
object		Upload request parameters.

Parameters

ParameterDescription
mkdir_parents
boolean		Create parent directories if they do not exist?

SDK Method

File.uploadStream()

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
destinationPath
string
Required		Remote path to upload the file/folder to.
readableStream
ReadableStream
Required		Readable stream to upload.
params
object		Upload request parameters.

Parameters

ParameterDescription
mkdir_parents
boolean		Create parent directories if they do not exist?

SDK Method

File.uploadFile()

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
destinationPath
string
Required		Remote path to upload the file/folder to.
sourceFilePath
string
Required		Local path of the file/folder to upload.
params
object		Upload request parameters.

Parameters

ParameterDescription
mkdir_parents
boolean		Create parent directories if they do not exist?

Upload File

import File from 'files.com/lib/models/File';
import { isBrowser } from 'files.com/lib/utils';
import * as FilesErrors from 'files.com/lib/Errors';

const params = { mkdir_parents: true };

try {
  // uploading raw file data
  await File.uploadData(destinationPath, data, params);
  
  // upload readable stream
  await File.uploadStream(destinationPath, readableStream, params)
  
  // uploading a file on disk (not available in browser)
  if (!isBrowser()) {
    await File.uploadFile(destinationPath, sourceFilePath, params);
  }
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Find File/Folder by Path

SDK Method

File.find()

Return Object

File

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
path
string
Required		Path to operate on.
preview_size
string		Request a preview size. Can be small (default), large, xlarge, or pdf.
with_previews
boolean		Include file preview information?
with_priority_color
boolean		Include file priority color information?

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  const file = await File.find(path, {
    with_previews: false,
  });
  // Operate on file
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

List Folders by Path

For historical reasons, and to maintain compatibility with a variety of other cloud-based MFT and EFSS services, Folders will always be listed before Files when listing a Folder. This applies regardless of the sorting parameters you provide. These will be used, after the initial sort application of Folders before Files.

SDK Method

Folder.listFor()

Return Object

File[]

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
path
string
Required		Path to operate on.
preview_size
string		Request a preview size. Can be small (default), large, xlarge, or pdf.
search
string		If specified, will search the folders/files list by name. Ignores text before last /. This is the same API used by the search bar in the web UI when running 'Search This Folder'. Search results are a best effort, not real time, and not guaranteed to perfectly match the latest folder listing. Results may be truncated if more than 1,000 possible matches exist. This field should only be used for ad-hoc (human) searching, and not as part of an automated process.
search_custom_metadata_key
string		If provided, the search string in search will search for files where this custom metadata key matches the value sent in search. Set this to * to allow any metadata key to match the value sent in search.
search_all
boolean		Search entire site? If true, we will search the entire site. Do not provide a path when using this parameter. This is the same API used by the search bar in the web UI when running 'Search All Files'. Search results are a best effort, not real time, and not guaranteed to match every file. This field should only be used for ad-hoc (human) searching, and not as part of an automated process.
with_previews
boolean		Include file previews?
with_priority_color
boolean		Include file priority color information?
type
string		Type of objects to return. Can be folder or file.
modified_at_datetime
string		If provided, will only return files/folders modified after this time. Can be used only in combination with type filter.

Additional Arguments

Example Request

import Folder from 'files.com/lib/models/Folder';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  const files = await Folder.listFor(path, {
    search: "some-partial-filename",
  });
  for (const file of files) {
    // Operate on file
  }
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Create Folder

SDK Method

Folder.create()

Return Object

File

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
path
string
Required		Path to operate on.
mkdir_parents
boolean		Create parent directories if they do not exist?
provided_mtime
string		User provided modification time.

Example Request

import Folder from 'files.com/lib/models/Folder';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  const file = await Folder.create(path, {
    mkdir_parents: false,
  });
  // Operate on file
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Update File/Folder Metadata

SDK Method

file.update()

Return Object

File

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
custom_metadata
object		Custom metadata map of keys and values. Limited to 32 keys, 256 characters per key and 1024 characters per value.
provided_mtime
string		Modified time of file.
priority_color
string		Priority/Bookmark color of file.

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  // Find the file object by its path.
  const file = await File.find(path);
  await file.update({
    custom_metadata: {"key":"value"},
  });
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Delete File/Folder

SDK Method

file.delete()

Return Object

No return value.

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
recursive
boolean		If true, will recursively delete folders. Otherwise, will error on non-empty folders.

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  // Find the file object by its path.
  const file = await File.find(path);
  await file.delete({
    recursive: false,
  });
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Copy File/Folder

SDK Method

file.copy()

Return Object

FileAction

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
destination
string
Required		Copy destination path.
copy_behaviors
boolean		If copying a folder, also copy supported behaviors to the destination folder tree?
structure
boolean		Copy structure only?
overwrite
boolean		Overwrite existing file(s) in the destination?

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  // Find the file object by its path.
  const file = await File.find(path);
  await file.copy({
    destination: "destination",
  });
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Move File/Folder

SDK Method

file.move()

Return Object

FileAction

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
destination
string
Required		Move destination path.
overwrite
boolean		Overwrite existing file(s) in the destination?

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  // Find the file object by its path.
  const file = await File.find(path);
  await file.move({
    destination: "destination",
  });
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Transform a file and save the output to a destination path

SDK Method

file.transform()

Return Object

FileAction

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
destination
string
Required		Destination file path for the transformed output.
transform_type
string
Required		Transform type. Supported values are image_convert, document_convert, and files_transform_script_execute.
target_format
string
Required		Destination format to create.
script
string		Files TransformScript source. Required when transform_type is files_transform_script_execute.
width
int64		Maximum output width for image_convert.
height
int64		Maximum output height for image_convert.
overwrite
boolean		Overwrite existing file in the destination?

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  // Find the file object by its path.
  const file = await File.find(path);
  await file.transform({
    destination: "destination",
    transform_type: "transform_type",
    target_format: "target_format",
  });
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Decrypt a GPG-encrypted file and save it to a destination path

SDK Method

file.gpgDecrypt()

Return Object

FileAction

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
destination
string
Required		Destination file path for the decrypted file.
gpg_key_ids
array(int64)		GPG Key IDs to decrypt with. If omitted, every accessible private GPG key in the source workspace is used.
gpg_key_partner_id
int64		Partner ID whose GPG keys should be used for decryption.
use_all_private_keys
boolean		Use every accessible private GPG key in the source workspace for decryption.
ignore_mdc_error
boolean		Ignore errors from the MDC (modification detection code) check.
overwrite
boolean		Overwrite existing file in the destination?

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  // Find the file object by its path.
  const file = await File.find(path);
  await file.gpgDecrypt({
    destination: "destination",
  });
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Encrypt a file with GPG and save it to a destination path

SDK Method

file.gpgEncrypt()

Return Object

FileAction

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
destination
string
Required		Destination file path for the encrypted file.
gpg_key_ids
array(int64)		GPG Key IDs to encrypt with.
gpg_key_partner_id
int64		Partner ID whose GPG keys should be used for encryption.
signing_key_id
int64		Optional GPG Key ID to sign with.
armor
boolean		Output ASCII-armored encrypted data.
overwrite
boolean		Overwrite existing file in the destination?

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  // Find the file object by its path.
  const file = await File.find(path);
  await file.gpgEncrypt({
    destination: "destination",
  });
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Extract a ZIP file to a destination folder

SDK Method

file.unzip()

Return Object

FileAction

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
destination
string
Required		Destination folder path for extracted files.
filename
string		Optional single entry filename to extract.
overwrite
boolean		Overwrite existing files in the destination?

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  // Find the file object by its path.
  const file = await File.find(path);
  await file.unzip({
    destination: "destination",
  });
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Create a ZIP from one or more paths and save it to a destination path

SDK Method

File.zip()

Return Object

FileAction

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
paths
array(string)
Required		Paths to include in the ZIP.
destination
string
Required		Destination file path for the ZIP.
overwrite
boolean		Overwrite existing file in the destination?

Example Request

import File from 'files.com/lib/models/File';
import * as FilesErrors from 'files.com/lib/Errors';

try {
  const fileAction = await File.zip({
    paths: "paths",
    destination: "destination",
  });
  // Operate on fileAction
} catch (err) {
  if (err instanceof FilesErrors.NotAuthenticatedError) {
    console.error(`Authentication Error Occurred (${err.constructor.name}): ${err.error}`);
  } else if (err instanceof FilesErrors.FilesError) {
    console.error(`Unknown Error Occurred (${err.constructor.name}): ${err.error}`);
  } else {
    throw err;
  }
}

Upload to External Destinations

These SDK helpers upload files into external destinations without requiring callers to assemble destination-specific paths manually.

DestinationSDK MethodID Parameter
Remote ServeruploadToRemoteServerremoteServerId
SnapshotuploadToSnapshotsnapshotId
Child SiteuploadToChildSitesiteId

Example Request

await File.uploadToRemoteServer(remoteServerId, 'remote/path/to/file.txt', sourceFilePath, { mkdir_parents: true })
await File.uploadToSnapshot(snapshotId, 'remote/path/to/file.txt', sourceFilePath)
await File.uploadToChildSite(siteId, 'remote/path/to/file.txt', sourceFilePath)

Copy to External Destinations

These SDK helpers copy files or folders into external destinations without requiring callers to assemble destination-specific paths manually.

DestinationSDK MethodID Parameter
Remote ServercopyToRemoteServerremoteServerId
SnapshotcopyToSnapshotsnapshotId
Child SitecopyToChildSitesiteId

Example Request

await file.copyToRemoteServer(remoteServerId, 'remote/path/to/file.txt', { overwrite: true })
await file.copyToSnapshot(snapshotId, 'remote/path/to/file.txt')
await file.copyToChildSite(siteId, 'remote/path/to/file.txt')

Move to External Destinations

These SDK helpers move files or folders into external destinations without requiring callers to assemble destination-specific paths manually.

DestinationSDK MethodID Parameter
Remote ServermoveToRemoteServerremoteServerId
SnapshotmoveToSnapshotsnapshotId
Child SitemoveToChildSitesiteId

Example Request

await file.moveToRemoteServer(remoteServerId, 'remote/path/to/file.txt', { overwrite: true })
await file.moveToSnapshot(snapshotId, 'remote/path/to/file.txt')
await file.moveToChildSite(siteId, 'remote/path/to/file.txt')

The File Object

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

AttributeDescription
path
string		File/Folder path. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
created_by_id
int64		User ID of the User who created the file/folder
created_by_api_key_id
int64		ID of the API key that created the file/folder
created_by_as2_incoming_message_id
int64		ID of the AS2 Incoming Message that created the file/folder
created_by_automation_id
int64		ID of the Automation that created the file/folder
created_by_bundle_registration_id
int64		ID of the Bundle Registration that created the file/folder
created_by_inbox_id
int64		ID of the Inbox that created the file/folder
created_by_remote_server_id
int64		ID of the Remote Server that created the file/folder
created_by_sync_id
int64		ID of the Sync that created the file/folder
custom_metadata
object		Custom metadata map of keys and values. Limited to 32 keys, 256 characters per key and 1024 characters per value.
display_name
string		File/Folder display name
type
string		Type: directory or file.
size
int64		File/Folder size
created_at
date-time		File created date/time
last_modified_by_id
int64		User ID of the User who last modified the file/folder
last_modified_by_api_key_id
int64		ID of the API key that last modified the file/folder
last_modified_by_automation_id
int64		ID of the Automation that last modified the file/folder
last_modified_by_bundle_registration_id
int64		ID of the Bundle Registration that last modified the file/folder
last_modified_by_remote_server_id
int64		ID of the Remote Server that last modified the file/folder
last_modified_by_sync_id
int64		ID of the Sync that last modified the file/folder
mtime
date-time		File last modified date/time, according to the server. This is the timestamp of the last Files.com operation of the file, regardless of what modified timestamp was sent.
provided_mtime
date-time		File last modified date/time, according to the client who set it. Files.com allows desktop, FTP, SFTP, and WebDAV clients to set modified at times. This allows Desktop<->Cloud syncing to preserve modified at times.
crc32
string		File CRC32 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.
md5
string		File MD5 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.
sha1
string		File SHA1 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.
sha256
string		File SHA256 checksum. This is sometimes delayed, so if you get a blank response, wait and try again.
mime_type
string		MIME Type. This is determined by the filename extension and is not stored separately internally.
region
string		Region location
permissions
string		A short string representing the current user's permissions. Can be r (Read),w (Write),d (Delete), l (List) or any combination
subfolders_locked?
boolean		Are subfolders locked and unable to be modified?
is_locked
boolean		Is this folder locked and unable to be modified?
download_uri
string		Link to download file. Provided only in response to a download request.
direct_connection_info
DirectConnectionInfo		Optional direct connection information for direct Agent transfer attempts
priority_color
string		Bookmark/priority color of file/folder
preview_id
int64		File preview ID
preview
Preview		File preview