Module dropbox_sdk::files

Your intent when writing a file to some path. This is used to determine what constitutes a conflict and what the autorename strategy is. In some situations, the conflict behavior is identical: (a) If the target path doesn’t refer to anything, the file is always written; no conflict. (b) If the target path refers to a folder, it’s always a conflict. (c) If the target path refers to a file with identical contents, nothing gets written; no conflict. The conflict checking differs in the case where there’s a file at the target path with contents different from the contents you’re trying to write.

Functions

alpha_get_metadataDeprecatedunstable

Returns the metadata for a file or folder. This is an alpha endpoint compatible with the properties API. Note: Metadata for the root folder is unsupported.

alpha_uploadDeprecatedunstable

Create a new file with the contents provided in the request. Note that the behavior of this alpha endpoint is unstable and subject to change. Do not use this to upload a file larger than 150 MB. Instead, create an upload session with upload_session_start().

copyDeprecated

Copy a file or folder to a different location in the user’s Dropbox. If the source path is a folder all its contents will be copied.

copy_batchDeprecated

Copy multiple files or folders to different locations at once in the user’s Dropbox. This route will return job ID immediately and do the async copy job in background. Please use copy_batch_check() to check the job status.

copy_batch_checkDeprecated

Returns the status of an asynchronous job for copy_batch(). If success, it returns list of results for each entry.

copy_batch_check_v2

Returns the status of an asynchronous job for copy_batch_v2(). It returns list of results for each entry.

copy_batch_v2

Copy multiple files or folders to different locations at once in the user’s Dropbox. This route will replace copy_batch(). The main difference is this route will return status for each entry, while copy_batch() raises failure if any entry fails. This route will either finish synchronously, or return a job ID and do the async copy job in background. Please use copy_batch_check_v2() to check the job status.

copy_reference_get

Get a copy reference to a file or folder. This reference string can be used to save that file or folder to another user’s Dropbox by passing it to copy_reference_save().

copy_reference_save

Save a copy reference returned by copy_reference_get() to the user’s Dropbox.

copy_v2

Copy a file or folder to a different location in the user’s Dropbox. If the source path is a folder all its contents will be copied.

create_folderDeprecated

Create a folder at a given path.

create_folder_batch

Create multiple folders at once. This route is asynchronous for large batches, which returns a job ID immediately and runs the create folder batch asynchronously. Otherwise, creates the folders and returns the result synchronously for smaller inputs. You can force asynchronous behaviour by using the CreateFolderBatchArg::force_async flag. Use create_folder_batch_check() to check the job status.

create_folder_batch_check

Returns the status of an asynchronous job for create_folder_batch(). If success, it returns list of result for each entry.

create_folder_v2

Create a folder at a given path.

deleteDeprecated

Delete the file or folder at a given path. If the path is a folder, all its contents will be deleted too. A successful response indicates that the file or folder was deleted. The returned metadata will be the corresponding FileMetadata or FolderMetadata for the item at time of deletion, and not a DeletedMetadata object.

delete_batch

Delete multiple files/folders at once. This route is asynchronous, which returns a job ID immediately and runs the delete batch asynchronously. Use delete_batch_check() to check the job status.

delete_batch_check

Returns the status of an asynchronous job for delete_batch(). If success, it returns list of result for each entry.

delete_v2

Delete the file or folder at a given path. If the path is a folder, all its contents will be deleted too. A successful response indicates that the file or folder was deleted. The returned metadata will be the corresponding FileMetadata or FolderMetadata for the item at time of deletion, and not a DeletedMetadata object.

do_moveDeprecated

Move a file or folder to a different location in the user’s Dropbox. If the source path is a folder all its contents will be moved.

download

Download a file from a user’s Dropbox.

download_zip

Download a folder from the user’s Dropbox, as a zip file. The folder must be less than 20 GB in size and any single file within must be less than 4 GB in size. The resulting zip must have fewer than 10,000 total file and folder entries, including the top level folder. The input cannot be a single file. Note: this endpoint does not support HTTP range requests.

exportunstable

Export a file from a user’s Dropbox. This route only supports exporting files that cannot be downloaded directly and whose ExportResult::file_metadata has ExportInfo::export_as populated.

get_file_lock_batch

Return the lock metadata for the given list of paths.

get_metadata

Returns the metadata for a file or folder. Note: Metadata for the root folder is unsupported.

get_preview

Get a preview for a file. Currently, PDF previews are generated for files with the following extensions: .ai, .doc, .docm, .docx, .eps, .gdoc, .gslides, .odp, .odt, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .rtf. HTML previews are generated for files with the following extensions: .csv, .ods, .xls, .xlsm, .gsheet, .xlsx. Other formats will return an unsupported extension error.

get_temporary_link

Get a temporary link to stream content of a file. This link will expire in four hours and afterwards you will get 410 Gone. This URL should not be used to display content directly in the browser. The Content-Type of the link is determined automatically by the file’s mime type.

get_temporary_upload_link

Get a one-time use temporary upload link to upload a file to a Dropbox location.

get_thumbnail

Get a thumbnail for an image. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif, webp, ppm and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.

get_thumbnail_batch

Get thumbnails for a list of images. We allow up to 25 thumbnails in a single batch. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif, webp, ppm and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.

get_thumbnail_v2

Get a thumbnail for an image. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif, webp, ppm and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.

get_thumbnail_v2_app_auth

Get a thumbnail for an image. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif, webp, ppm and bmp. Photos that are larger than 20MB in size won’t be converted to a thumbnail.

list_folder

Starts returning the contents of a folder. If the result’s ListFolderResult::has_more field is true, call list_folder_continue() with the returned ListFolderResult::cursor to retrieve more entries. If you’re using ListFolderArg::recursive set to true to keep a local cache of the contents of a Dropbox account, iterate through each entry in order and process them as follows to keep your local state in sync: For each FileMetadata, store the new entry at the given path in your local state. If the required parent folders don’t exist yet, create them. If there’s already something else at the given path, replace it and remove all its children. For each FolderMetadata, store the new entry at the given path in your local state. If the required parent folders don’t exist yet, create them. If there’s already something else at the given path, replace it but leave the children as they are. Check the new entry’s FolderSharingInfo::read_only and set all its children’s read-only statuses to match. For each DeletedMetadata, if your local state has something at the given path, remove it and all its children. If there’s nothing at the given path, ignore this entry. Note: auth::RateLimitError may be returned if multiple list_folder() or list_folder_continue() calls with same parameters are made simultaneously by same API app for same user. If your app implements retry logic, please hold off the retry until the previous request finishes.

list_folder_app_auth

Starts returning the contents of a folder. If the result’s ListFolderResult::has_more field is true, call list_folder_continue() with the returned ListFolderResult::cursor to retrieve more entries. If you’re using ListFolderArg::recursive set to true to keep a local cache of the contents of a Dropbox account, iterate through each entry in order and process them as follows to keep your local state in sync: For each FileMetadata, store the new entry at the given path in your local state. If the required parent folders don’t exist yet, create them. If there’s already something else at the given path, replace it and remove all its children. For each FolderMetadata, store the new entry at the given path in your local state. If the required parent folders don’t exist yet, create them. If there’s already something else at the given path, replace it but leave the children as they are. Check the new entry’s FolderSharingInfo::read_only and set all its children’s read-only statuses to match. For each DeletedMetadata, if your local state has something at the given path, remove it and all its children. If there’s nothing at the given path, ignore this entry. Note: auth::RateLimitError may be returned if multiple list_folder() or list_folder_continue() calls with same parameters are made simultaneously by same API app for same user. If your app implements retry logic, please hold off the retry until the previous request finishes.

list_folder_continue

Once a cursor has been retrieved from list_folder(), use this to paginate through all files and retrieve updates to the folder, following the same rules as documented for list_folder().

list_folder_continue_app_auth

Once a cursor has been retrieved from list_folder(), use this to paginate through all files and retrieve updates to the folder, following the same rules as documented for list_folder().

list_folder_get_latest_cursor

A way to quickly get a cursor for the folder’s state. Unlike list_folder(), list_folder_get_latest_cursor() doesn’t return any entries. This endpoint is for app which only needs to know about new files and modifications and doesn’t need to know about files that already exist in Dropbox.

list_folder_longpoll

A longpoll endpoint to wait for changes on an account. In conjunction with list_folder_continue(), this call gives you a low-latency way to monitor an account for file changes. The connection will block until there are changes available or a timeout occurs. This endpoint is useful mostly for client-side apps. If you’re looking for server-side notifications, check out our webhooks documentation.

list_revisions

Returns revisions for files based on a file path or a file id. The file path or file id is identified from the latest file entry at the given file path or id. This end point allows your app to query either by file path or file id by setting the mode parameter appropriately. In the ListRevisionsMode::Path (default) mode, all revisions at the same file path as the latest file entry are returned. If revisions with the same file id are desired, then mode must be set to ListRevisionsMode::Id. The ListRevisionsMode::Id mode is useful to retrieve revisions for a given file across moves or renames.

lock_file_batch

Lock the files at the given paths. A locked file will be writable only by the lock holder. A successful response indicates that the file has been locked. Returns a list of the locked file paths and their metadata after this operation.

move_batchDeprecated

Move multiple files or folders to different locations at once in the user’s Dropbox. This route will return job ID immediately and do the async moving job in background. Please use move_batch_check() to check the job status.

move_batch_checkDeprecated

Returns the status of an asynchronous job for move_batch(). If success, it returns list of results for each entry.

move_batch_check_v2

Returns the status of an asynchronous job for move_batch_v2(). It returns list of results for each entry.

move_batch_v2

Move multiple files or folders to different locations at once in the user’s Dropbox. Note that we do not currently support case-only renaming. This route will replace move_batch(). The main difference is this route will return status for each entry, while move_batch() raises failure if any entry fails. This route will either finish synchronously, or return a job ID and do the async move job in background. Please use move_batch_check_v2() to check the job status.

move_v2

Move a file or folder to a different location in the user’s Dropbox. If the source path is a folder all its contents will be moved. Note that we do not currently support case-only renaming.

paper_createunstable

Creates a new Paper doc with the provided content.

paper_updateunstable

Updates an existing Paper doc with the provided content.

permanently_delete

Permanently delete the file or folder at a given path (see https://www.dropbox.com/en/help/40). If the given file or folder is not yet deleted, this route will first delete it. It is possible for this route to successfully delete, then fail to permanently delete. Note: This endpoint is only available for Dropbox Business apps.

properties_addDeprecated

properties_overwriteDeprecated

properties_removeDeprecated

properties_template_getDeprecated

properties_template_listDeprecated

properties_updateDeprecated

restore

Restore a specific revision of a file to the given path.

save_url

Save the data from a specified URL into a file in user’s Dropbox. Note that the transfer from the URL must complete within 5 minutes, or the operation will time out and the job will fail. If the given path already exists, the file will be renamed to avoid the conflict (e.g. myfile (1).txt).

save_url_check_job_status

Check the status of a save_url() job.

searchDeprecated

Searches for files and folders. Note: Recent changes will be reflected in search results within a few seconds and older revisions of existing files may still match your query for up to a few days.

search_continue_v2

Fetches the next page of search results returned from search_v2(). Note: search_v2() along with search_continue_v2() can only be used to retrieve a maximum of 10,000 matches. Recent changes may not immediately be reflected in search results due to a short delay in indexing. Duplicate results may be returned across pages. Some results may not be returned.

search_v2

Searches for files and folders. Note: search_v2() along with search_continue_v2() can only be used to retrieve a maximum of 10,000 matches. Recent changes may not immediately be reflected in search results due to a short delay in indexing. Duplicate results may be returned across pages. Some results may not be returned.

tags_addunstable

Add a tag to an item. A tag is a string. The strings are automatically converted to lowercase letters. No more than 20 tags can be added to a given item.

tags_getunstable

Get list of tags assigned to items.

tags_removeunstable

Remove a tag from an item.

unlock_file_batch

Unlock the files at the given paths. A locked file can only be unlocked by the lock holder or, if a business account, a team admin. A successful response indicates that the file has been unlocked. Returns a list of the unlocked file paths and their metadata after this operation.

upload

Create a new file with the contents provided in the request. Do not use this to upload a file larger than 150 MB. Instead, create an upload session with upload_session_start(). Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

upload_session_appendDeprecated

Append more data to an upload session. A single request should not upload more than 150 MB. The maximum size of a file one can upload to an upload session is 350 GB. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

upload_session_append_v2

Append more data to an upload session. When the parameter close is set, this call will close the session. A single request should not upload more than 150 MB. The maximum size of a file one can upload to an upload session is 350 GB. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

upload_session_finish

Finish an upload session and save the uploaded data to the given file path. A single request should not upload more than 150 MB. The maximum size of a file one can upload to an upload session is 350 GB. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

upload_session_finish_batchDeprecated

This route helps you commit many files at once into a user’s Dropbox. Use upload_session_start() and upload_session_append_v2() to upload file contents. We recommend uploading many files in parallel to increase throughput. Once the file contents have been uploaded, rather than calling upload_session_finish(), use this route to finish all your upload sessions in a single request. UploadSessionStartArg::close or UploadSessionAppendArg::close needs to be true for the last upload_session_start() or upload_session_append_v2() call. The maximum size of a file one can upload to an upload session is 350 GB. This route will return a job_id immediately and do the async commit job in background. Use upload_session_finish_batch_check() to check the job status. For the same account, this route should be executed serially. That means you should not start the next job before current job finishes. We allow up to 1000 entries in a single request. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

upload_session_finish_batch_check

Returns the status of an asynchronous job for upload_session_finish_batch(). If success, it returns list of result for each entry.

upload_session_finish_batch_v2

This route helps you commit many files at once into a user’s Dropbox. Use upload_session_start() and upload_session_append_v2() to upload file contents. We recommend uploading many files in parallel to increase throughput. Once the file contents have been uploaded, rather than calling upload_session_finish(), use this route to finish all your upload sessions in a single request. UploadSessionStartArg::close or UploadSessionAppendArg::close needs to be true for the last upload_session_start() or upload_session_append_v2() call of each upload session. The maximum size of a file one can upload to an upload session is 350 GB. We allow up to 1000 entries in a single request. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

upload_session_start

Upload sessions allow you to upload a single file in one or more requests, for example where the size of the file is greater than 150 MB. This call starts a new upload session with the given data. You can then use upload_session_append_v2() to add more data and upload_session_finish() to save all the data to a file in Dropbox. A single request should not upload more than 150 MB. The maximum size of a file one can upload to an upload session is 350 GB. An upload session can be used for a maximum of 7 days. Attempting to use an UploadSessionStartResult::session_id with upload_session_append_v2() or upload_session_finish() more than 7 days after its creation will return a UploadSessionLookupError::NotFound. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page. By default, upload sessions require you to send content of the file in sequential order via consecutive upload_session_start(), upload_session_append_v2(), upload_session_finish() calls. For better performance, you can instead optionally use a UploadSessionType::Concurrent upload session. To start a new concurrent session, set UploadSessionStartArg::session_type to UploadSessionType::Concurrent. After that, you can send file data in concurrent upload_session_append_v2() requests. Finally finish the session with upload_session_finish(). There are couple of constraints with concurrent sessions to make them work. You can not send data with upload_session_start() or upload_session_finish() call, only with upload_session_append_v2() call. Also data uploaded in upload_session_append_v2() call must be multiple of 4194304 bytes (except for last upload_session_append_v2() with UploadSessionStartArg::close to true, that may contain any remaining data).