Bundles

A Bundle is the API/SDK term for the feature called Share Links in the web interface. The API provides the full set of actions related to Share Links, including sending them via E-Mail.

Please note that we very closely monitor the E-Mailing feature and any abuse will result in disabling of your site.

Command

files-cli bundles list

Output

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

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Parameter access is subject to this endpoint's authorization requirement and the caller's access to the affected resource. Site Administrator access also includes Site-Wide API keys.

Flag	Description
--user-id= int64	User ID. Provide a value of `0` to operate the current session's user. Can be set by: Site Administrator; Read-only Administrator; Workspace Administrator.
--deleted boolean	If true, only list deleted Share Links.

Additional Arguments

Example Request

files-cli bundles list \
  --user-id=1

Command

files-cli bundles find

Output

Outputs a Bundle object according to the output format.

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Flag	Description
--id= int64 Required	Bundle ID.
--deleted boolean	If true, show a deleted Share Link.

Example Request

files-cli bundles find \
  --id=1

Command

files-cli bundles create

Output

Outputs a Bundle object according to the output format.

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Parameter access is subject to this endpoint's authorization requirement and the caller's access to the affected resource. Site Administrator access also includes Site-Wide API keys.

Flag	Default	Description
--user-id= int64		User ID. Provide a value of `0` to operate the current session's user. Can be set by: Site Administrator; Workspace Administrator.
--paths= array(string) Required		A list of paths to include in this bundle.
--password= string		Password for this bundle.
--bypasses-site-expiration-rules boolean	`false`	If true, this Share Link bypasses site-wide expiration rules. Only site admins may set this. Can be set by: Site Administrator.
--form-field-set-id= int64		Id of Form Field Set to use with this bundle
--create-snapshot boolean		If true, create a snapshot of this bundle's contents.
--dont-separate-submissions-by-folder boolean	`false`	Do not create subfolders for files uploaded to this share. 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.
--expires-at= string		Explicit Bundle expiration date/time. If not set, the site-wide expiration setting may apply.
--finalize-snapshot boolean		If true, finalize the snapshot of this bundle's contents. Note that `create_snapshot` must also be true.
--max-uses= int64		Maximum number of times bundle can be accessed
--group-id= int64		Owning group ID. If set, members of this group can view, edit, and share this Share Link.
--internal-name= string		Internal name for identifying this Share Link.
--description= string		Public description
--note= string		Bundle internal note
--code= string		Bundle code. This code forms the end part of the Public URL.
--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.
--permissions= string	`"read"`	Permissions that apply to Folders in this Share Link. Possible values: `read`, `write`, `read_write`, `full`, `none`, `preview_only`
--require-registration boolean	`false`	Show a registration page that captures the downloader's name and email address?
--clickwrap-id= int64		ID of the clickwrap to use with this bundle.
--inbox-id= int64		ID of the associated inbox, if available.
--require-share-recipient boolean	`false`	Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI?
--send-one-time-password-to-recipient-at-registration boolean	`false`	If true, require_share_recipient bundles will send a one-time password to the recipient when they register. Cannot be enabled if the bundle has a password set.
--send-email-receipt-to-uploader boolean	`false`	Send delivery receipt to the uploader. Note: For writable share only
--skip-email boolean		BundleRegistrations can be saved without providing email?
--skip-name boolean		BundleRegistrations can be saved without providing name?
--skip-company boolean		BundleRegistrations can be saved without providing company?
--start-access-on-date= string		Date when share will start to be accessible. If `nil` access granted right after create.
--snapshot-id= int64		ID of the snapshot containing this bundle's contents.
--workspace-id= int64	`0`	Workspace ID. `0` means the default workspace.
--watermark-attachment-file= file		Preview watermark image applied to all bundle items. See Attaching Files to API Requests.
--watermark-value= object		Preview watermark settings applied to all bundle items. Uses the same keys as Behavior.value

Example Request

files-cli bundles create \
  --paths="["file.txt"]"

Send email(s) with a link to bundle

Command

files-cli bundles share

Output

No output is returned.

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Flag	Description
--id= int64 Required	Bundle ID.
--to= array(string)	A list of email addresses to share this bundle with. Required unless `recipients` is used.
--note= string	Note to include in email.
--recipients= array(object)	A list of recipients to share this bundle with. Required unless `to` is used.

Example Request

files-cli bundles share \
  --id=1

Command

files-cli bundles update

Output

Outputs a Bundle object according to the output format.

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Parameter access is subject to this endpoint's authorization requirement and the caller's access to the affected resource. Site Administrator access also includes Site-Wide API keys.

Flag	Description
--id= int64 Required	Bundle ID.
--paths= array(string)	A list of paths to include in this bundle.
--password= string	Password for this bundle.
--bypasses-site-expiration-rules boolean	If true, this Share Link bypasses site-wide expiration rules. Only site admins may set this. Can be set by: Site Administrator.
--form-field-set-id= int64	Id of Form Field Set to use with this bundle
--clickwrap-id= int64	ID of the clickwrap to use with this bundle.
--code= string	Bundle code. This code forms the end part of the Public URL.
--create-snapshot boolean	If true, create a snapshot of this bundle's contents.
--description= string	Public description
--dont-separate-submissions-by-folder boolean	Do not create subfolders for files uploaded to this share. 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.
--expires-at= string	Explicit Bundle expiration date/time. If not set, the site-wide expiration setting may apply.
--finalize-snapshot boolean	If true, finalize the snapshot of this bundle's contents. Note that `create_snapshot` must also be true.
--inbox-id= int64	ID of the associated inbox, if available.
--max-uses= int64	Maximum number of times bundle can be accessed
--group-id= int64	Owning group ID. If set, members of this group can view, edit, and share this Share Link. Can be set by: Site Administrator; Workspace Administrator.
--internal-name= string	Internal name for identifying this Share Link.
--note= string	Bundle internal note
--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.
--permissions= string	Permissions that apply to Folders in this Share Link. Possible values: `read`, `write`, `read_write`, `full`, `none`, `preview_only`
--require-registration boolean	Show a registration page that captures the downloader's name and email address?
--require-share-recipient boolean	Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI?
--send-one-time-password-to-recipient-at-registration boolean	If true, require_share_recipient bundles will send a one-time password to the recipient when they register. Cannot be enabled if the bundle has a password set.
--send-email-receipt-to-uploader boolean	Send delivery receipt to the uploader. Note: For writable share only
--skip-company boolean	BundleRegistrations can be saved without providing company?
--start-access-on-date= string	Date when share will start to be accessible. If `nil` access granted right after create.
--skip-email boolean	BundleRegistrations can be saved without providing email?
--skip-name boolean	BundleRegistrations can be saved without providing name?
--user-id= int64	The owning user id. Only site admins can set this. Can be set by: Site Administrator; Workspace Administrator.
--watermark-attachment-delete boolean	If true, will delete the file stored in watermark_attachment
--watermark-attachment-file= file	Preview watermark image applied to all bundle items. See Attaching Files to API Requests.
--watermark-value= object	Preview watermark settings applied to all bundle items. Uses the same keys as Behavior.value
--workspace-id= int64	Workspace ID. `0` means the default workspace.

Example Request

files-cli bundles update \
  --id=1 \
  --paths="["file.txt"]"

Command

files-cli bundles delete

Output

No output is returned.

Authorization Requirement

Available to all authenticated keys or sessions.

Flags

Flag	Description
--id= int64 Required	Bundle ID.

Example Request

files-cli bundles delete \
  --id=1

The Bundle Object

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

Attribute	Description
code string	Bundle code. This code forms the end part of the Public URL.
color_left string	Page link and button color
color_link string	Top bar link color
color_text string	Page link and button color
color_top string	Top bar background color
color_top_text string	Top bar text color
url string	Public URL of Share Link
description string	Public description
expires_at date-time	Explicit Bundle expiration date/time. If not set, the site-wide expiration setting may apply.
password_protected boolean	Is this bundle password protected?
permissions string	Permissions that apply to Folders in this Share Link. Possible values: `read`, `write`, `read_write`, `full`, `none`, `preview_only`
preview_only boolean
require_registration boolean	Show a registration page that captures the downloader's name and email address?
require_share_recipient boolean	Only allow access to recipients who have explicitly received the share via an email sent through the Files.com UI?
require_logout boolean	If true, we will hide the 'Remember Me' box on the Bundle registration page, requiring that the user logout and log back in every time they visit the page.
clickwrap_body string	Legal text that must be agreed to prior to accessing Bundle.
form_field_set FormFieldSet	Custom Form to use
skip_name boolean	BundleRegistrations can be saved without providing name?
skip_email boolean	BundleRegistrations can be saved without providing email?
start_access_on_date date-time	Date when share will start to be accessible. If `nil` access granted right after create.
skip_company boolean	BundleRegistrations can be saved without providing company?
id int64	Bundle ID
bypasses_site_expiration_rules boolean	If true, this Share Link bypasses site-wide expiration rules. Only site admins may set this.
created_at date-time	Bundle created at date/time
deleted boolean	Indicates if the bundle has been deleted.
deleted_at date-time	Bundle deleted at date/time
dont_separate_submissions_by_folder boolean	Do not create subfolders for files uploaded to this share. 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.
effective_expires_at date-time	Read-only expiration date/time, using the explicit expiration or the site-wide setting when applicable. Null when the Share Link does not expire.
max_uses int64	Maximum number of times bundle can be accessed
internal_name string	Internal name for identifying this Share Link.
note string	Bundle internal note
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.
send_email_receipt_to_uploader boolean	Send delivery receipt to the uploader. Note: For writable share only
snapshot_id int64	ID of the snapshot containing this bundle's contents.
user_id int64	Bundle creator user ID
username string	Bundle creator username
group_id int64	Owning group ID. If set, members of this group can view, edit, and share this Share Link.
clickwrap_id int64	ID of the clickwrap to use with this bundle.
inbox_id int64	ID of the associated inbox, if available.
watermark_attachment Image	Preview watermark image applied to all bundle items.
watermark_value object	Preview watermark settings applied to all bundle items. Uses the same keys as Behavior.value
send_one_time_password_to_recipient_at_registration boolean	If true, require_share_recipient bundles will send a one-time password to the recipient when they register. Cannot be enabled if the bundle has a password set.
workspace_id int64	Workspace ID. `0` means the default workspace.
has_inbox boolean	Does this bundle have an associated inbox?
dont_allow_folders_in_uploads boolean	Should folder uploads be prevented?
requested_upload_slots array(object)	Upload slots requested by the associated Inbox. Each slot contains a name used as its label and destination subfolder name.
paths array(string)	A list of paths in this bundle. For performance reasons, this is not provided when listing bundles.
bundlepaths array(object)	A list of bundlepaths in this bundle. For performance reasons, this is not provided when listing bundles.

watermark_value

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 watermark_value

{
  "gravity": "SouthWest",
  "max_height_or_width": 20,
  "transparency": 25
}

requested_upload_slots

Upload slots requested by the associated Inbox. Each slot contains a name used as its label and destination subfolder name.

Value type	Description
array of objects	Upload slots requested by the associated Inbox. Each slot contains a name used as its label and destination subfolder name.

Example requested_upload_slots

[
  {
    "name": "Photo ID"
  }
]

Bundles

List Share Links

Command

Output

Authorization Requirement

Flags

Additional Arguments

Pagination

Sorting

Filtering

Show Share Link

Command

Output

Authorization Requirement

Flags

Create Share Link

Command

Output

Authorization Requirement

Flags

Send email(s) with a link to bundle

Command

Output

Authorization Requirement

Flags

Update Share Link

Command

Output

Authorization Requirement

Flags

Delete Share Link

Command

Output

Authorization Requirement

Flags

The Bundle Object

watermark_value

requested_upload_slots

Requested upload slot