Behaviors

A Behavior is an API resource for what are also known as Folder Settings. Every behavior is associated with a folder.

Depending on the behavior, it may also operate on child folders. It may be overridable at the child folder level or maybe can be added to at the child folder level. The exact options for each behavior type are explained in the table below.

Each behavior type also has a recursion mode in the behavior type documentation. always means the behavior is always recursive, never means it is never recursive, and sometimes means callers may choose the value of the recursive field.

Additionally, some behaviors are visible to non-admins, and others are even settable by non-admins. All the details are below.

Each behavior uses a different format for its settings value. The accepted fields and an example are shown with each behavior type. In the REST API, send these settings as JSON within the value field.

Note: Append Timestamp behavior removed. Check Override Upload Filename behavior which have even more functionality to modify name on upload.

Webhook Behaviors

Sends an HTTP(S) request to a remote server whenever certain actions occur on a folder. Webhooks are often used to integrate Files.com with other services.

Behavior Details
Behavior type	`webhook`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. Additional behaviors may be set directly on child folders.
Only one may be set per folder?	No
Visible to non-admins?	No
Requires attachment?	No

Value Hash Parameter	Description
urls array of strings Required	Array of URLs to send the webhook to. At least 1 item.
method string	Default: `GET`. May also be set to `POST`.
triggers array of strings	Leave blank or use `*` to send webhooks on any action on this folder. Otherwise, specify an array of action types.
triggering_filenames array of strings	Leave blank to trigger webhooks on any file in this folder. Or you may specify an array of filenames (possibly with wildcards) to match for action path.
exclude_filenames array of strings	Leave blank and no files will be excluded. Or specify an array of filenames (with optional wildcards) to exclude certain files from triggering the webhook based on their name. This setting takes precedence over the `triggering_filenames` setting if a path matches both settings.
encoding string	May be `JSON`, `XML`, `RAW`, `EV1`, or `EV2`. If set to `RAW` or left blank, we will deliver the webhook using the HTTP GET params or POST body. If JSON or XML, we will encode the payload accordingly and send a matching `Content-Type` header. If set to EV1, we will encode the payload to emulate ExaVault's version 1 webhook format. If set to EV2, we will encode the payload to emulate ExaVault's version 2.0 webhook format.
headers object of string values	Hash of HTTP Headers to send.
body object	Hash of Body Params to send.
verification_token string	If provided, this token will be used to sign webhook messages cryptographically to allow you to verify the webhook authenticity.
file_form_field string	A string specifying the name of a form field containing the contents of the file that triggered this webhook send. If this value is present, the webhook will submit a `multipart/form-data` POST with no request body encoding.
file_as_body boolean	When sending webhook requests, submit the contents of the file that triggered this webhook send as the request body.
use_dedicated_ips boolean	If set to true, we will send webhooks from dedicated IPs. This is useful if you need to whitelist IPs for your webhook endpoint.

Example Request

files-cli behaviors create \
  --value='{"urls":["https://example.com/webhook"],"method":"POST","encoding":"JSON"}' \
  --path="path" \
  --behavior="webhook"

File Expiration Behaviors

Files in this folder will expire (be deleted) after a certain number of days. This is most often used for compliance purposes where different types of data may need different retention settings. It's also great for managing your costs. You can retain different data for less time than others.

Value is stored as a hash containing days_to_retain and any additional options such as delete_empty_folders.

Behavior Details
Behavior type	`file_expiration`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
days_to_retain integer Required	Number of days to keep files around. Minimum: 1.
delete_empty_folders boolean	If `true`, delete empty folders inside this tree after expired files are removed. Folders with explicit configuration, such as permissions, notifications, or behaviors, are preserved. Default: `false`.

Example Request

files-cli behaviors create \
  --value='{"days_to_retain":30,"delete_empty_folders":false}' \
  --path="path" \
  --behavior="file_expiration"

Auto Encrypt Behaviors

Files will be automatically encrypted after uploading using your provided GPG keys.

This Behavior is often used on our HIPAA accounts to convert data into a format unreadable by even us. GPG is an asymmetric encryption type (which means it uses public keys and private keys). Because you are only providing us your public keys and keeping your private keys, we won't be able to read anything once it has been GPG encrypted.

Behavior Details
Behavior type	`auto_encrypt`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child. Auto Decrypt will be also overridden.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
gpg_key_id integer	Your GPG Key ID object to use for this operation. Minimum: 1. References gpg key by ID.
gpg_key_ids array of integers	Your GPG Key ID objects to use for this operation. At least 1 item. Values must be unique. Each item must be at least 1.
algorithm string Required	Must be set to `PGP/GPG`. If we support other options in the future (like OpenSSL), we will amend this option. Value: `PGP/GPG`.
signing_key_id integer	Optional GPG Key ID object to use for signing the encrypted file. Minimum: 1. References gpg key by ID.
suffix string	Suffix to apply to filenames once they've been uploaded.
armor boolean	If `true`, encrypted files are written as ASCII text.
gpg_key_partner_id integer	If set, use the Partner's key for encryption. Minimum: 1. References partner by ID.
key_md5 string	MD5 digest of the configured public key material. Read only.
private_key_md5 string	MD5 digest of the configured private key material. Read only.
private_key_password_md5 string	MD5 digest of the configured private key password. Read only.
signing_key_md5 string	MD5 digest of the configured signing key material. Read only.
signing_key_password_md5 string	MD5 digest of the configured signing key password. Read only.

Example Request

files-cli behaviors create \
  --value='{"gpg_key_ids":[1],"algorithm":"PGP/GPG","suffix":".gpg","armor":false}' \
  --path="path" \
  --behavior="auto_encrypt"

Lock Subfolders Behaviors

The subfolder structure of this folder may not be changed. This is useful in conjunction with workflows and automations to ensure your folder structure stays as you expect.

children_recursive - Do not allow Create/Move/Delete on parent folder, child folders and any descendant folders.

children - Do not allow Create/Move/Delete on parent folder or child folders but do allow on any descendant folders.

self - Do not allow Delete or Rename of this(parent) folder. Do allow Create/Move/Delete on child folders and any descendant folders.

Behavior Details
Behavior type	`lock_subfolders`
Recursion and override behavior	Always recursively applied to child folders. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
level string	Which folders the lock applies to. Can be `children_recursive` (default), `children`, `self`, or `none`. Possible values: `children_recursive`, `children`, `self`, `none`.

Example Request

files-cli behaviors create \
  --value='{"level":"children_recursive"}' \
  --path="path" \
  --behavior="lock_subfolders"

Storage Region Behaviors

Files in this folder are stored in a certain geographical region. If you set this Behavior on an existing folder, we will migrate existing files to the new location automatically.

Region	Description
`us-east-1`	USA, East - Northern Virginia
`eu-west-1`	EU - Ireland

Behavior Details
Behavior type	`storage_region`
Recursion and override behavior	Always recursively applied to child folders. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value type	Description
string	Valid AWS region. Possible values: `us-east-1`, `eu-west-1`.

Example Request

files-cli behaviors create \
  --value='"us-east-1"' \
  --path="path" \
  --behavior="storage_region"

Serve Publicly Behaviors

Files in this folder are served via a public HTTPS URL at https://SUBDOMAIN.hosted-by-files.com/...

This feature works with common static site generators such as Jekyll and Middleman, and allows any static web assets or website to be hosted. It's a great way to get extra mileage out of your Files.com account and avoid having to pay for separate web hosting.

Behavior Details
Behavior type	`serve_publicly`
Recursion and override behavior	Always recursively applied to child folders. Additional behaviors may be set directly on child folders.
Only one may be set per folder?	No
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
key string	URL path for where the stuff is publicly hosted. It will look like `https://SUBDOMAIN.hosted-by-files.com/{key}/`.
show_index boolean	If true, show an index page listing the folder contents. Default: `false`.
force_download boolean	If true, send the Content-Disposition: attachment header, instructing browsers to always download files and not display them in the browser. Default: `false`.
username string	Username required to access the publicly hosted folder.
password string	Password required to access the publicly hosted folder. Write only.
password_required boolean	Whether password authentication is configured. Read only.
cors_enabled boolean	Enable CORS headers for cross-origin requests Default: `false`.
require_site_authentication boolean	Require Files.com site authentication before visitors can access this publicly hosted folder. Default: `false`.

Example Request

files-cli behaviors create \
  --value='{"key":"public-files","show_index":true,"force_download":false}' \
  --path="path" \
  --behavior="serve_publicly"

Create User Folders Behaviors

Create a folder here for new users when they are added. This behavior is never recursive. It only applies to the folder where it is configured. This Behavior is typically used to implement home folders for users. It's also a good building block for more advanced automations and workflows.

Behavior Details
Behavior type	`create_user_folders`
Recursion and override behavior	Never applied to child folders. Additional behaviors may be set directly on child folders.
Only one may be set per folder?	No
Visible to non-admins?	No
Requires attachment?	No

Value Hash Parameter	Description
permission string	What permission level to give the user on his or her new folder? Takes the same options as the Permissions endpoint. Possible values: `full`, `readonly`, `writeonly`, `list`, `history`, `admin`, `bundle`, `site_admin`, `readonly_site_admin`, `previewonly`.
additional_permission string	Additional permission level to give the user on his or her new folder. Used to apply a second permission. Takes the same options as the Permissions endpoint. Possible values: `full`, `readonly`, `writeonly`, `list`, `history`, `admin`, `bundle`, `site_admin`, `readonly_site_admin`, `previewonly`.
existing_users boolean	Apply this behavior to existing users or only newly added users? Default: `false`.
group_id integer	Only apply this behavior to users who are members of this group ID. Minimum: 1. References group by ID.
new_folder_name string	What to name the new folder. Currently we support `name` and `username`. `name` will fall back to `username` if not present. Default value is `name`. Possible values: `name`, `username`.
subfolders array of strings	Subfolders to create within the new folder.

Example Request

files-cli behaviors create \
  --value='{"permission":"full","existing_users":false,"new_folder_name":"name"}' \
  --path="path" \
  --behavior="create_user_folders"

Inbox Behaviors

This folder operates as an inbox where anonymous users can upload files without logging in.

Path Templates

Admins can customize how submission subfolders are created by providing a path_template value. For example, an inbox can be created with the following path_template value:

{{name}}_{{ip}}

This will result in submission subfolders that look like john doe_127.0.0.1.

Path templates can use any of the following standard fields:

name
company
email
email_domain
ip

They can also use any fields defined on the inbox's custom form field set. An inbox with a custom form field set with a field called 'My Field' can have a path template that looks like this:

{{name}}_{{My Field}}

Note: Field names are case-sensitive.

Behavior Details
Behavior type	`inbox`
Recursion and override behavior	Always recursively applied to child folders. Additional behaviors may be set directly on child folders.
Only one may be set per folder?	No
Visible to non-admins?	No
Requires attachment?	No

Value Hash Parameter	Description
key string Required	URL key used for the inbox. May only contain lowercase alphabetic characters, numbers, and dashes.
dont_separate_submissions_by_folder boolean	Do not create subfolders for files uploaded to this inbox. Note: there are subtle security pitfalls with allowing anonymous uploads from multiple users to live in the same folder. We strongly discourage use of this option unless absolutely required. Default: `false`.
dont_separate_submissions_by_folder_for_inbound_email boolean	Do not create subfolders for inbound email uploads to this inbox. This exists for backwards compatibility for older inboxes that already used inbound email. Default: `false`.
dont_allow_folders_in_uploads boolean	If set to `true`, will prevent folders from being created inside an inbox submission. Useful for certain automation use cases where nested folders don't work well. Default: `false`.
require_inbox_recipient boolean	If set to `true`, requires that the inbox be shared with specific recipients rather than being accessed via a URL directly. Default: `false`.
show_on_login_page boolean	Show this inbox on the login page of your website. Only settable by admins. Default: `false`.
clickwrap_id integer	Clickwrap ID required before submitting to the Inbox. Minimum: 1. References clickwrap by ID.
form_field_set_id integer	Form Field Set ID used by the Inbox. Minimum: 1. References form field set by ID.
title string Required	Title of the Inbox. Must be unique per site. Maximum length: 550.
description string	Description of the inbox shown on the actual inbox page.
help_text string	Help text shown on the inbox page.
require_registration boolean	Show a registration page that captures the uploader's name and email address? Default: `false`.
password string	Password to authenticate to inbox. Write only.
has_password_hash boolean	Whether password authentication is configured. Read only.
path_template string	Template for creating submission subfolders. Can use the uploader's name, email address, ip, company, `strftime` directives, and any custom form data.
path_template_time_zone string	Timezone to use when rendering timestamps in path templates.
enable_inbound_email_address boolean	This is only used when creating/updating a behavior. If set to `true`, will generate inbound_email_address to this folder. If set to `false`, will remove inbound_email_address to this folder. Please note that the uploads via email doesn't work if require_registration or password options are set to `true`. Write only.
inbound_email_address string	Generated inbound email address. Read only.
notify_senders_on_successful_uploads_via_email boolean	If `true`, notify the sender on successful uploads via email. Default: `false`.
notify_senders_on_successful_uploads_via_web boolean	Notify senders on successful uploads via web. Please note that the notifications on web uploads only works if require_registration is set to `true`. Default: `false`.
allow_whitelisting boolean	If `true`, only allow uploads from whitelisted email addresses and domains. Default: `false`.
whitelist string	Comma-separated string of whitelisted email addresses and domains.
disable_web_upload boolean	If `true`, disable the upload URL. Can only be done if uploads via email are enabled. Default: `false`.
capture_email_body_filename string	If set, the plain-text body of email submissions will be saved with this name.
requested_upload_slots array of objects	Upload slots requested on the public Inbox page. Each slot name is used as its label and destination subfolder name.

Requested upload slot

Attribute	Description
name string Required	Upload slot label and destination subfolder name.

Example Request

files-cli behaviors create \
  --value='{"key":"application-forms","dont_separate_submissions_by_folder":false,"show_on_login_page":false,"title":"Application Forms","require_registration":false,"disable_web_upload":false,"requested_upload_slots":[{"name":"Photo ID"}]}' \
  --path="path" \
  --behavior="inbox"

Limit File Extensions Behaviors

Restricts uploads to this folder based on file extension. Use mode: "whitelist" to allow only the listed extensions, or mode: "blacklist" to block them.

Behavior Details
Behavior type	`limit_file_extensions`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
extensions array of strings Required	Array of whitelisted/blacklisted file extensions, depending on `mode`. At least 1 item. Values must be unique.
mode string	Controls whether the behavior acts as a whitelist or as a blacklist. Default is `whitelist`. Possible values: `whitelist`, `blacklist`. Default: `whitelist`.

Example Request

files-cli behaviors create \
  --value='{"extensions":["pdf","csv"],"mode":"whitelist"}' \
  --path="path" \
  --behavior="limit_file_extensions"

Limit File Regex Behaviors

Limit the filenames of files in this folder according to a regular expression.

Behavior Details
Behavior type	`limit_file_regex`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value type	Description
array of strings	Single-element Array (not a hash) containing the regular expression, which must start and end with slashes. From 1 to 1 items.

Example Request

files-cli behaviors create \
  --value='["/Document-.*/"]' \
  --path="path" \
  --behavior="limit_file_regex"

Sends a notification via Amazon SNS whenever certain actions occur on a folder.

Behavior Details
Behavior type	`amazon_sns`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. Additional behaviors may be set directly on child folders.
Only one may be set per folder?	No
Visible to non-admins?	No
Requires attachment?	No

Value Hash Parameter	Description
arns array of strings Required	Array of ARNs to send the notifications to. At least 1 item.
triggers array of strings	Leave blank or use `*` to send an SNS notification on any action on this folder. Otherwise, specify an array of action types.
aws_credentials object	AWS IAM Credentials to use for sending SNS requests. Must include `access_key_id`, and `secret_access_key`.
body object	Additional body parameters to include in the notification.

AWS credentials

Attribute	Description
access_key_id string Required
region string
secret_access_key string Required	Write only.

Example Request

files-cli behaviors create \
  --value='{"arns":["arn:aws:sns:us-east-1:123456789012:files-events"],"aws_credentials":{"access_key_id":"ACCESS_KEY_ID","region":"us-east-1","secret_access_key":"SECRET_ACCESS_KEY"}}' \
  --path="path" \
  --behavior="amazon_sns"

Watermark Behaviors

Adds a watermark to any image preview generated for an image in this folder.

Behavior Details
Behavior type	`watermark`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	No
Requires attachment?	Yes

Value Hash Parameter	Description
gravity string	Where to locate the watermark? Valid values: `Center`, `East`, `NorthEast`, `North`, `NorthWest`, `SouthEast`, `South`, `SouthWest`, `West`. Possible values: `Center`, `East`, `NorthEast`, `North`, `NorthWest`, `SouthEast`, `South`, `SouthWest`, `West`.
max_height_or_width integer	Max width/height as percent of image preview.
transparency integer	Percentage applied to the watermark.
dynamic_text string	Watermark text. Use {{user}} to embed a username into the string.

Example Request

files-cli behaviors create \
  --value='{"gravity":"SouthWest","max_height_or_width":20,"transparency":25}' \
  --path="path" \
  --behavior="watermark"

Remote Server Mount Behaviors

Mount a remote server within this folder. Remote servers can be FTP/SFTP servers, Amazon S3/GCP/Azure Blob/Wasabi/Backblaze B2 Buckets, and more.

See the RemoteServer object for a full list of the Remote Servers supported.

When this behavior is enabled, files in this folder will never actually be stored on Files.com. Rather, Files.com will mount the remote server and act as a mere conduit from your clients to the remote server.

Files.com workflow elements such as Permissions, Automations, Webhooks, Notifications, etc., will apply only to transfer activities that occur through Files.com. We won't send Webhooks or Notifications based on activity that occurs via a direct connection to the Remote Server other than through Files.com.

Behavior Details
Behavior type	`remote_server_mount`
Recursion and override behavior	Always recursively applied to child folders. Cannot be overridden by behaviors on child folders.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
remote_server_id integer Required	ID of the remote server to mount. See the Remote Servers API resource for managing these. Minimum: 1. References remote server by ID.
remote_path string	Path on remote server to treat as the root of this mount. This should be an absolute path on the remote server. This must be slash-delimited, but it must neither start nor end with a slash, and it must not contain relative path components.

Example Request

files-cli behaviors create \
  --value='{"remote_server_id":1,"remote_path":"shared/files"}' \
  --path="path" \
  --behavior="remote_server_mount"

Slack Webhook Behaviors

Displays a message in Slack (via a Slack webhook) whenever certain actions occur on a folder. You will need to add the "Incoming WebHooks" App to your Slack workspace.

Behavior Details
Behavior type	`slack_webhook`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. Additional behaviors may be set directly on child folders.
Only one may be set per folder?	No
Visible to non-admins?	No
Requires attachment?	No

Value Hash Parameter	Description
url string Required	Slack issued URL to send the webhook to.
username string	Username to display in Slack.
channel string	Channel is send the webhook to.
icon_emoji string	Slack emoji to display in Slack, e.g. :robot_face:.
triggers array of strings	Leave blank or use `*` to send webhooks on any action on this folder. Otherwise, specify an array of action types.

Example Request

files-cli behaviors create \
  --value='{"url":"https://hooks.slack.com/services/example","triggers":["create"]}' \
  --path="path" \
  --behavior="slack_webhook"

Auto Decrypt Behaviors

Files will be automatically decrypted after uploading using your provided GPG keys.

Behavior Details
Behavior type	`auto_decrypt`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child. Auto Encrypt will be also overridden.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
gpg_key_id integer	Your GPG Key ID object to use for this operation. Minimum: 1. References gpg key by ID.
gpg_key_ids array of integers	Your GPG Key ID objects to use for this operation. At least 1 item. Values must be unique. Each item must be at least 1.
algorithm string Required	Must be set to `PGP/GPG`. If we support other options in the future (like OpenSSL), we will amend this option. Value: `PGP/GPG`.
suffix string	Filename suffix that if present will be removed after decryption.
ignore_mdc_error boolean	Set to true if you want to ignore any errors from the MDC (modification detection code) check.
gpg_key_partner_id integer	If set, use the Partner's key for decryption. Minimum: 1. References partner by ID.
use_all_private_keys boolean	If set, use every accessible private GPG key in this behavior's workspace for decryption instead of specific GPG key IDs.
key_md5 string	MD5 digest of the configured public key material. Read only.
private_key_md5 string	MD5 digest of the configured private key material. Read only.
private_key_password_md5 string	MD5 digest of the configured private key password. Read only.

Example Request

files-cli behaviors create \
  --value='{"gpg_key_ids":[1],"algorithm":"PGP/GPG","suffix":".gpg","ignore_mdc_error":false}' \
  --path="path" \
  --behavior="auto_decrypt"

Override Upload Filename Behaviors

Modify filenames of files uploaded to this folder. You can mix flags with regular chars and use anything accepted by the standard UNIX date command or strftime.

Upload Path

To reference the upload path folders, use %p1, %p2, %p3, etc. for the first, second, third, etc. path folder, respectively. To reference upload path folders from the root downward, use %P1, %P2, %P3, etc. for the first, second, third, etc. path folder, respectively.

For example, if the upload path is personal/accounts/file.txt, then the pattern %p1_%Ff will result in the actual file name being accounts_file.txt. If you pick non existing level e.g. %p7 it will evaluate it to empty string. If the upload path is partner/app/team/inbound/file.txt, then the pattern %P1_%P3_%Ff will result in the actual file name being partner_team_file.txt.

List of available patterns:

%Fl - original filename, with extension, converted to lowercase
%Ff - original filename, with extension
%Fe - original extension
%Fp - original filename with extension, removed spaces, converted to lower case and non ASCII characters normalized to ASCII to ensure widest compatibility.
%Fb - original filename, without extension
%Fn - original filename without non-alphanumeric characters, with extension
%pX - reference to the upload path folders, where X should be integer number starting from 1 to point the upload path folder level
%PX - reference to the upload path folders from the root downward, where X should be integer number starting from 1 to point the upload path folder level

To perform a regular expression replacement after the filename override and simple replacement, use filename_regex_replace_from and filename_regex_replace_to. Capture groups may be referenced in the replacement using Ruby-style backreferences such as \1 or named backreferences such as \k<name>. JavaScript-style backreferences such as $1 and ${name} are also accepted.

Behavior Details
Behavior type	`override_upload_filename`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
filename_override_pattern string	Format for filename override. You may use anything from the list `%Fl, %Ff, %Fe, %Fb, %Fp, %Fb, %Fn, %pX, %PX`. You can mix flags with regular chars and use anything accepted by the standard UNIX `date` command or `strftime`.
filename_replace_from string	If provided, we will replace this string in the filename with the value in `filename_replace_to`. This replacement is performed after the other patterns are applied.
filename_replace_to string	If `filename_replace_from` is provided, this value will be used to replace it in the filename. This replacement is performed after the other patterns are applied.
filename_regex_replace_from string	If provided, we will replace text matched by this regular expression in the filename with the value in `filename_regex_replace_to`. Capture groups may be referenced in `filename_regex_replace_to` using Ruby-style backreferences such as `\1` or named backreferences such as `\k<name>`. JavaScript-style backreferences such as `$1` and `${name}` are also accepted. This replacement is performed after simple filename replacement.
filename_regex_replace_to string	If `filename_regex_replace_from` is provided, this value will replace regular expression matches in the filename. Capture groups may be referenced using `\1`, `\k<name>`, `$1`, or `${name}`. This replacement is performed after simple filename replacement.
time_zone string	Accepts any valid timezone value from the web interface (e.g. "Eastern Time (US & Canada)") or a UTC offset ("-05:00"). Omit parameter for UTC time.

Example Request

files-cli behaviors create \
  --value='{"filename_override_pattern":"%Fb_uploaded%Fe"}' \
  --path="path" \
  --behavior="override_upload_filename"

Permission Fence Behaviors

Apply Permission fence to a folder.

Ignores user/group upward permissions and only applies downward permissions or permissions on the folder itself.

Does not apply to Site Admins.

Behavior Details
Behavior type	`permission_fence`
Recursion and override behavior	Always recursively applied to child folders. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	No
Requires attachment?	No

Value Hash Parameter	Description
fenced_permissions string	Which permissions to fence. Currently only 'all' is supported. Value: `all`.

Example Request

files-cli behaviors create \
  --value='{"fenced_permissions":"all"}' \
  --path="path" \
  --behavior="permission_fence"

Limit Filename Length Behaviors

Limit the length of filenames in this folder, and optionally shorten them if they exceed the limit.

Behavior Details
Behavior type	`limit_filename_length`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
max_length integer Required	Number of characters to limit filenames to. Minimum: 10.
shorten boolean	Shorten the filename if it exceeds the maximum length. Default: `false`.

Example Request

files-cli behaviors create \
  --value='{"max_length":30,"shorten":true}' \
  --path="path" \
  --behavior="limit_filename_length"

Organize Files Into Subfolders Behaviors

Organize uploaded files into subfolders based on configuration settings. When the rule is in place, any file uploaded will be placed into the subdirectory. There is also an option to apply the rule to files already exiting in the folder. This behavior is never recursive. It only applies to the folder where it is configured.

The types of configuration

extension - organize uploaded files into directories named after the file extensions (ie, file.txt will be in subfolder /txt/)

regex - a passed in regular expression applied to the file name will determine the new subfolder (ie, the regex /(?<=\-)[0-9]{1}|(?<=\.)[a-z]{3}/)/ applied to file123.txt will put the file into subfolder /1/txt/ )

provided_modified_at - organize uploaded files according to the passed in modified_at date, the name of the subdirectory is determined by a passed strftime format (ie, the format of %Y-%m-%d will put a file with provided_modified_at of Jan 1, 2024 into /2024-01-01/ )

created_at - organize uploaded files according to the created_at date, the name of the subdirectory is determined by a passed strftime format (ie, the format of %Y-%m-%d will put a file with created_at of Jan 1, 2024 into /2024-01-01/ )

At the time of either behavior creation or updating, a passed in parameter of apply_behavior=true will start a File Migration that will apply the rule to each file already in the folder

Behavior Details
Behavior type	`organize_files_into_subfolders`
Recursion and override behavior	Never applied to child folders. Additional behaviors may be set directly on child folders.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
subfolder_name_type string Required	Subfolder creation type for this folder. Possible values: `regex`, `extension`, `created_at`, `provided_modified_at`.
regex string	Valid regular expression used to determine the subfolder name. This is used when `subfolder_name_type` is `regex`.
strftime_format string	DateTime string format used to determine the subfolder name. This is used when `subfolder_name_type` is `created_at` or `provided_modified_at`.
time_zone string	Time zone (in Rails TimeZone name format) to be used when interpreting `strftime_format`. If not set, UTC will be used.
apply_behavior boolean	If `true`, apply the current behavior (new or existing) to the files in the folder. Write only.

Example Request

files-cli behaviors create \
  --value='{"subfolder_name_type":"extension"}' \
  --path="path" \
  --behavior="organize_files_into_subfolders"

Teams Webhook Behaviors

Displays a message in Microsoft Teams (via Teams webhook integration) whenever certain actions occur on a folder. You will need to generate a webhook URL in your Microsoft Teams workspace.

Behavior Details
Behavior type	`teams_webhook`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. Additional behaviors may be set directly on child folders.
Only one may be set per folder?	No
Visible to non-admins?	No
Requires attachment?	No

Value Hash Parameter	Description
url string Required	Teams issued URL to send the webhook to.
triggers array of strings	Leave blank or use `*` to send webhooks on any action on this folder. Otherwise, specify an array of action types.

Example Request

files-cli behaviors create \
  --value='{"url":"https://example.webhook.office.com/webhook","triggers":["create"]}' \
  --path="path" \
  --behavior="teams_webhook"

Google Pub Sub Behaviors

Sends a notification via Google Pub/Sub whenever certain actions occur on a folder.

Behavior Details
Behavior type	`google_pub_sub`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. Additional behaviors may be set directly on child folders.
Only one may be set per folder?	No
Visible to non-admins?	No
Requires attachment?	No

Value Hash Parameter	Description
projects_topics array of objects Required	Array of pairs of project_id => topic_id to send the notification to. topic_id must be the Pub/Sub topic ID, not a full resource path or publish endpoint. At least 1 item.
triggers array of strings	Leave blank or use `*` to publish a notification on any action on this folder. Otherwise, specify an array of action types.
google_credentials object Required	Google Service Account credentials used to send Google Pub/Sub requests.
body object	Additional body parameters to include in the notification.

Google Pub/Sub project and topic

Attribute	Description
project_id string Required
topic_id string Required

Google service account credentials

Attribute	Description
type string
project_id string
private_key_id string
private_key string	Write only.
client_email string
client_id string
auth_uri string
token_uri string
auth_provider_x509_cert_url string
client_x509_cert_url string
universe_domain string

Example Request

files-cli behaviors create \
  --value='{"projects_topics":[{"project_id":"my-project","topic_id":"files-events"}],"google_credentials":{"type":"service_account","project_id":"your-project-id","private_key_id":"your-private-key-id","private_key":"-----BEGIN PRIVATE KEY-----\\nMIIC...","client_email":"your-service-account@your-project-id.iam.gserviceaccount.com","client_id":"your-client-id","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"https://www.googleapis.com/robot/v1/metadata/x509/your-service-account%40your-project-id.iam.gserviceaccount.com"}}' \
  --path="path" \
  --behavior="google_pub_sub"

Archive Overwritten Or Deleted Files Behaviors

When file or folder is being deleted or overwriten, the object is moved to the configured archive_path instead of being destroyed.

Behavior Details
Behavior type	`archive_overwritten_or_deleted_files`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	No
Requires attachment?	No

Value Hash Parameter	Description
archive_path string Required	Absolute path where deleted or overwritten items will be relocated.

Example Request

files-cli behaviors create \
  --value='{"archive_path":"/Archive"}' \
  --path="path" \
  --behavior="archive_overwritten_or_deleted_files"

Auto Recrypt Behaviors

Files will be automatically recrypted (decrypted and re-encrypted with a different key) after uploading using your provided GPG keys.

This Behavior is often used on our HIPAA accounts to convert data into a format unreadable by even us. GPG is an asymmetric encryption type (which means it uses public keys and private keys). Because you are only providing us your public key when re-encrypting and keeping your private keys, we won't be able to read anything once it has been GPG encrypted.

Behavior Details
Behavior type	`auto_recrypt`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child. Auto Recrypt will be also overridden.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
decrypt_gpg_key_ids array of integers	Your GPG Key ID object(s) to use for decryption. At least 1 item. Values must be unique. Each item must be at least 1.
encrypt_gpg_key_ids array of integers	Your GPG Key ID object(s) to use for encryption. At least 1 item. Values must be unique. Each item must be at least 1.
decrypt_gpg_key_partner_id integer	If set, use the Partner's key for decryption. Minimum: 1. References partner by ID.
encrypt_gpg_key_partner_id integer	If set, use the Partner's key for encryption. Minimum: 1. References partner by ID.
ignore_mdc_error boolean	Set to true if you want to ignore any errors from the MDC (modification detection code) check.
signing_key_id integer	Optional GPG Key ID object to use for signing the encrypted file. Minimum: 1. References gpg key by ID.
armor boolean	If `true`, encrypted files are written as ASCII text.

Example Request

files-cli behaviors create \
  --value='{"decrypt_gpg_key_ids":[1],"encrypt_gpg_key_ids":[2],"ignore_mdc_error":false,"armor":false}' \
  --path="path" \
  --behavior="auto_recrypt"

Metadata Category Behaviors

Assigns a MetadataCategory to a folder. The category defines a reusable set of Custom Metadata rules (key names, allowed values, and default columns) for files in the folder.

Multiple MetadataCategory behaviors can be assigned to a folder and its children.

Behavior Details
Behavior type	`metadata_category`
Recursion and override behavior	Always recursively applied to child folders. Additional behaviors may be set directly on child folders.
Only one may be set per folder?	No
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
metadata_category_id integer Required	ID of the MetadataCategory to assign to this folder. Minimum: 1. References metadata category by ID.

Example Request

files-cli behaviors create \
  --value='{"metadata_category_id":1}' \
  --path="path" \
  --behavior="metadata_category"

Auto Unzip Behaviors

ZIP files will be automatically extracted after upload. The ZIP file remains in place, and the contents are extracted by a FileMigration unzip job.

Behavior Details
Behavior type	`auto_unzip`
Recursion and override behavior	Recursively applied to child folders if `recursive` option is set. May be overridden in the child by adding a behavior on the child.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
destination_path string Required	Absolute folder path where ZIP contents will be extracted. Supports automation-style path tokens such as strftime directives, `%p1`, `%P1`, `%Ff`, and `%tf`.
path_time_zone string	Timezone to use when rendering timestamp tokens in destination_path.

Example Request

files-cli behaviors create \
  --value='{"destination_path":"/Uploads/Unzipped/%Y/%m/%d"}' \
  --path="path" \
  --behavior="auto_unzip"

Remote Server Metadata Index Behaviors

Polls a mounted remote folder and creates or updates local MetadataDm records for each remote item.

This is the supported way to use polling-triggered Automations on remote folders: combine it with an action-triggered Automation. It is also the supported way to index a remote folder for search.

Behavior Details
Behavior type	`remote_server_metadata_index`
Recursion and override behavior	Always recursively applied to child folders. Cannot be overridden by behaviors on child folders.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description
interval_minutes integer	Frequency, in minutes, for polling the remote folder and indexing remote metadata locally. Default: `1440`. Minimum: 5.
initial_scan_completed boolean	System-managed flag that indicates whether the initial metadata index scan has completed. Read only.

Example Request

files-cli behaviors create \
  --value='{"interval_minutes":1440}' \
  --path="path" \
  --behavior="remote_server_metadata_index"

Malware Scanning Behaviors

Files uploaded to this folder are held as pending while they are scanned for malware.

Behavior Details
Behavior type	`malware_scanning`
Recursion and override behavior	Always recursively applied to child folders. Cannot be overridden by behaviors on child folders.
Only one may be set per folder?	Yes
Visible to non-admins?	Yes
Requires attachment?	No

Value Hash Parameter	Description

Example Request

files-cli behaviors create \
  --value='{}' \
  --path="path" \
  --behavior="malware_scanning"

List Behaviors

Command

files-cli behaviors list

Output

Outputs a list of Behavior objects according to the output format.

Authorization Requirement

Available to all authenticated keys or sessions.

Additional Arguments

Example Request

files-cli behaviors list

Show Behavior

Command

files-cli behaviors find

Output

Outputs a Behavior object according to the output format.

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Flag	Description
--id= int64 Required	Behavior ID.

Example Request

files-cli behaviors find \
  --id=1

List Behaviors by Path

Command

files-cli behaviors list-for

Output

Outputs a list of Behavior objects according to the output format.

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Flag	Description
--path= string Required	Path to operate on.
--ancestor-behaviors boolean	If `true`, behaviors above this path are shown.

Additional Arguments

Example Request

files-cli behaviors list-for \
  --path="path"

Create Behavior

Command

files-cli behaviors create

Output

Outputs a Behavior object according to the output format.

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Flag	Description
--value= object	This field stores data specific to the type of behavior. See The Behavior Types section for the accepted value for each type of behavior.
--attachment-file= file	Certain behaviors may require a file, for instance, the `watermark` behavior requires a watermark image. Attach that file here. See Attaching Files to API Requests.
--disable-parent-folder-behavior boolean	If `true`, the parent folder's behavior will be disabled for this folder and its children. This is the main mechanism for canceling out a `recursive` behavior higher in the folder tree.
--recursive boolean	Whether the behavior should apply to child folders. This is only configurable for behavior types whose recursion mode is `sometimes`; `always` behaviors stay recursive and `never` behaviors stay non-recursive.
--name= string	Name for this behavior.
--description= string	Description for this behavior.
--path= string Required	Path where this behavior should apply.
--behavior= string Required	Behavior type.

Example Request

files-cli behaviors create \
  --path="path" \
  --behavior="webhook"

Test Webhook

Command

files-cli behaviors webhook-test

Output

No output is returned.

Authorization Requirement

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

Flags

Flag	Description
--url= string Required	URL for testing the webhook.
--method= string	HTTP request method (GET or POST).
--encoding= string	Encoding type for the webhook payload. Can be JSON, XML, or RAW (form data).
--headers= object	Additional request headers to send via HTTP.
--body= object	Additional body parameters to include in the webhook payload.

Example Request

files-cli behaviors webhook-test \
  --url="https://www.site.com/..."

Update Behavior

Command

files-cli behaviors update

Output

Outputs a Behavior object according to the output format.

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Flag	Description
--id= int64 Required	Behavior ID.
--value= object	This field stores data specific to the type of behavior. See The Behavior Types section for the accepted value for each type of behavior.
--attachment-file= file	Certain behaviors may require a file, for instance, the `watermark` behavior requires a watermark image. Attach that file here. See Attaching Files to API Requests.
--disable-parent-folder-behavior boolean	If `true`, the parent folder's behavior will be disabled for this folder and its children. This is the main mechanism for canceling out a `recursive` behavior higher in the folder tree.
--recursive boolean	Whether the behavior should apply to child folders. This is only configurable for behavior types whose recursion mode is `sometimes`; `always` behaviors stay recursive and `never` behaviors stay non-recursive.
--name= string	Name for this behavior.
--description= string	Description for this behavior.
--attachment-delete boolean	If `true`, delete the file stored in `attachment`.

Example Request

files-cli behaviors update \
  --id=1

Delete Behavior

Command

files-cli behaviors delete

Output

No output is returned.

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Flag	Description
--id= int64 Required	Behavior ID.

Example Request

files-cli behaviors delete \
  --id=1

The Behavior Object

Some of the commands above return a Behavior object. The attributes of this object are listed below.

Attribute	Description
id int64	Folder behavior ID
path string	Folder path. Note that Behavior paths cannot be updated once initially set. You will need to remove and re-create the behavior on the new path. This must be slash-delimited, but it must neither start nor end with a slash. Maximum of 5000 characters.
attachment_url string	URL for attached file
behavior string	Behavior type. Possible values: `webhook`, `file_expiration`, `auto_encrypt`, `lock_subfolders`, `storage_region`, `serve_publicly`, `create_user_folders`, `inbox`, `limit_file_extensions`, `limit_file_regex`, `amazon_sns`, `watermark`, `remote_server_mount`, `slack_webhook`, `auto_decrypt`, `override_upload_filename`, `permission_fence`, `limit_filename_length`, `organize_files_into_subfolders`, `teams_webhook`, `google_pub_sub`, `archive_overwritten_or_deleted_files`, `auto_recrypt`, `metadata_category`, `auto_unzip`, `remote_server_metadata_index`, `malware_scanning`
name string	Name for this behavior.
description string	Description for this behavior.
value object	Settings for this behavior. See the section above for an example value to provide here. Formatting is different for each Behavior type. May be sent as nested JSON or a single JSON-encoded string. If using XML encoding for the API call, this data must be sent as a JSON-encoded string.
public_hosting_url string	Public URL for this publicly hosted folder when the `Serve Publicly` behavior has a key configured. When a Custom Domain with `public_hosting` destination is attached to this behavior, the URL uses that domain. Otherwise it uses the site's `subdomain.hosted-by-files.com` host.
disable_parent_folder_behavior boolean	If true, the parent folder's behavior will be disabled for this folder and its children.
recursive boolean	Whether this behavior is recursive for this record. `always` behaviors are always `true`, `never` behaviors are always `false`, and `sometimes` behaviors may be either value.
inherited boolean	If true, this behavior is inherited from a higher scope rather than owned by the requested workspace.
managed boolean	If true, this behavior is controlled by a parent-site policy and cannot be modified locally.
root_behavior_site_admin_only boolean	If true, this behavior may only be modified by a site admin because it is at the site root or disables a root behavior.

`value`

Settings for a Behavior. The accepted value shape is selected by the sibling behavior property.

Example value

{
  "urls": [
    "https://example.com/webhook"
  ],
  "method": "POST",
  "encoding": "JSON"
}

Behaviors

Requested upload slot

AWS credentials

Google Pub/Sub project and topic

Google service account credentials

Command

Output

Authorization Requirement

Additional Arguments

Pagination

Sorting

Filtering

Command

Output

Authorization Requirement

Flags

Command

Output

Authorization Requirement

Flags

Additional Arguments

Pagination

Sorting

Filtering

Command

Output

Authorization Requirement

Flags

Command

Output

Authorization Requirement

Flags

Command

Output

Authorization Requirement

Flags

Command

Output

Authorization Requirement

Flags

value

`value`