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 Function
File.download();
Return Object
File
Authorization Requirement
Available to all authenticated keys or sessions.
Function Arguments
| Argument | Description |
|---|---|
| path string Required | Path to operate on. |
Note
This function only prepares a File object for download. To actually download the file, combine this function with one of the below functions.
Save File to Local Disk
SDK Function
file.saveAsLocalFile();
Function Arguments
| Argument | Description |
|---|---|
| path String Required | Local path to download the file to. |
Upload File
SDK Function
File.create();
Return Object
File
Authorization Requirement
Available to all authenticated keys or sessions.
Function Arguments
| Argument | Description |
|---|---|
| path string Required | Path to operate on. |
| parameters HashMap Required | Upload request parameters. |
Parameters
| Parameter | Description |
|---|---|
| mkdir_parents boolean | Create parent directories if they do not exist? |
Note
This function only prepares a FileUploadPart object for upload. To actually upload file content, combine this function with one of the below functions.
Upload Local File
SDK Function
file.putLocalFile();
Function Arguments
| Argument | Description |
|---|---|
| path String Required | Local path of the file to upload. |
Upload File Contents
SDK Function
file.putInputStream();
Function Arguments
| Argument | Description |
|---|---|
| inputStream InputStream Required | Input stream of the file to upload. |
| date Date Required | Unused parameter. |
| threadCount int Required | Number of threads to use for parallelized upload. |
Find File/Folder by Path
SDK Function
File.find()
Return Object
File
Authorization Requirement
Available to all authenticated keys or sessions.
Function Arguments
| Argument | Description |
|---|---|
| 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? |
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 Function
Folder.listFor()
Return Object
ListIterator<File>
Authorization Requirement
Available to all authenticated keys or sessions.
Function Arguments
| Argument | Description |
|---|---|
| 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
Create Folder
SDK Function
Folder.create()
Return Object
File
Authorization Requirement
Available to all authenticated keys or sessions.
Function Arguments
| Argument | Description |
|---|---|
| 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. |
Update File/Folder Metadata
SDK Function
file.update();
Return Object
File
Authorization Requirement
Available to all authenticated keys or sessions.
Attribute Setters
| Setter | Description |
|---|---|
| setCustomMetadata object | Custom metadata map. Replaces existing metadata; an empty map clears it. Requires Full or Admin permission. Uploaders with Write permission can supply custom metadata when completing an upload instead. |
| setProvidedMtime string | Modified time of file. |
| setPriorityColor string | Priority/Bookmark color of file. |
Delete File/Folder
SDK Function
file.delete();
Return Object
No return value.
Authorization Requirement
Available to all authenticated keys or sessions.
Attribute Setters
| Setter | Description |
|---|---|
| setRecursive boolean | If true, will recursively delete folders. Otherwise, will error on non-empty folders. |
Create a ZIP from one or more paths and save it to a destination path
SDK Function
File.zip()
Return Object
FileAction
Authorization Requirement
Available to all authenticated keys or sessions.
Function Arguments
| Argument | Description |
|---|---|
| paths array(string) Required | Paths to include in the ZIP. |
| destination string Required | Destination file path for the ZIP. |
| archive_format string | Archive format to create. Possible values: zip, tar, tar.gz, tgz |
| overwrite boolean | Overwrite existing file in the destination? |
Extract a ZIP file to a destination folder
SDK Function
file.unzip();
Return Object
FileAction
Authorization Requirement
Available to all authenticated keys or sessions.
Attribute Setters
| Setter | Description |
|---|---|
| setDestination string Required | Destination folder path for extracted files. |
| setFilename string | Optional single entry filename to extract. |
| setOverwrite boolean | Overwrite existing files in the destination? |
Encrypt a file with GPG and save it to a destination path
SDK Function
file.gpgEncrypt();
Return Object
FileAction
Authorization Requirement
Available to all authenticated keys or sessions.
Attribute Setters
| Setter | Description |
|---|---|
| setDestination string Required | Destination file path for the encrypted file. |
| setGpgKeyIds array(int64) | GPG Key IDs to encrypt with. |
| setGpgKeyPartnerId int64 | Partner ID whose GPG keys should be used for encryption. |
| setSigningKeyId int64 | Optional GPG Key ID to sign with. |
| setArmor boolean | Output ASCII-armored encrypted data. |
| setOverwrite boolean | Overwrite existing file in the destination? |
Decrypt a GPG-encrypted file and save it to a destination path
SDK Function
file.gpgDecrypt();
Return Object
FileAction
Authorization Requirement
Available to all authenticated keys or sessions.
Attribute Setters
| Setter | Description |
|---|---|
| setDestination string Required | Destination file path for the decrypted file. |
| setGpgKeyIds array(int64) | GPG Key IDs to decrypt with. If omitted, every accessible private GPG key in the source workspace is used. |
| setGpgKeyPartnerId int64 | Partner ID whose GPG keys should be used for decryption. |
| setUseAllPrivateKeys boolean | Use every accessible private GPG key in the source workspace for decryption. |
| setIgnoreMdcError boolean | Ignore errors from the MDC (modification detection code) check. |
| setOverwrite boolean | Overwrite existing file in the destination? |
Transform a file and save the output to a destination path
SDK Function
file.transform();
Return Object
FileAction
Authorization Requirement
Available to all authenticated keys or sessions.
Attribute Setters
| Setter | Description |
|---|---|
| setDestination string Required | Destination file path for the transformed output. |
| setTransformType string Required | Transform type. Supported values are image_convert, document_convert, and files_transform_script_execute. |
| setTargetFormat string Required | Destination format to create. |
| setScript string | Files TransformScript source. Required when transform_type is files_transform_script_execute. |
| setWidth int64 | Maximum output width for image_convert. |
| setHeight int64 | Maximum output height for image_convert. |
| setOverwrite boolean | Overwrite existing file in the destination? |
Move File/Folder
SDK Function
file.move();
Return Object
FileAction
Authorization Requirement
Available to all authenticated keys or sessions.
Attribute Setters
| Setter | Description |
|---|---|
| setDestination string Required | Move destination path. |
| setOverwrite boolean | Overwrite existing file(s) in the destination? |
Copy File/Folder
SDK Function
file.copy();
Return Object
FileAction
Authorization Requirement
Available to all authenticated keys or sessions.
Attribute Setters
| Setter | Description |
|---|---|
| setDestination string Required | Copy destination path. |
| setCopyBehaviors boolean | If copying a folder, also copy supported behaviors, email notification subscriptions, and per-folder branding to the destination folder tree? |
| setStructure boolean | Copy structure only? |
| setOverwrite boolean | Overwrite existing file(s) in the destination? |
Delete File/Folder and return its File Action. A pending or processing deletion continues in the background after this returns; check its File Migration for completion. Waiting for the File Migration does not cancel the deletion
SDK Function
file.beginDelete();
Return Object
FileAction
Authorization Requirement
Available to all authenticated keys or sessions.
Attribute Setters
| Setter | Description |
|---|---|
| setRecursive boolean | If true, will recursively delete folders. Otherwise, will error on non-empty folders. |
Upload to External Destinations
These SDK helpers upload files into external destinations without requiring callers to assemble destination-specific paths manually.
| Destination | SDK Method | ID Parameter |
|---|---|---|
| Remote Server | uploadToRemoteServer | remoteServerId |
| Snapshot | uploadToSnapshot | snapshotId |
| Child Site | uploadToChildSite | siteId |
Copy to External Destinations
These SDK helpers copy files or folders into external destinations without requiring callers to assemble destination-specific paths manually.
| Destination | SDK Method | ID Parameter |
|---|---|---|
| Remote Server | copyToRemoteServer | remoteServerId |
| Snapshot | copyToSnapshot | snapshotId |
| Child Site | copyToChildSite | siteId |
Move to External Destinations
These SDK helpers move files or folders into external destinations without requiring callers to assemble destination-specific paths manually.
| Destination | SDK Method | ID Parameter |
|---|---|---|
| Remote Server | moveToRemoteServer | remoteServerId |
| Snapshot | moveToSnapshot | snapshotId |
| Child Site | moveToChildSite | siteId |
The File Object
Some of the functions above return a File object. The attributes of this object are listed below.
| Attribute | Description |
|---|---|
| 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 |
custom_metadata
Custom metadata map of keys and values. Limited to 32 keys, 256 characters per key and 1024 characters per value.
| Value type | Description |
|---|---|
| object of string values | Custom metadata map of keys and values. Limited to 32 keys, 256 characters per key and 1024 characters per value. At most 32 keys. |