dropbox.dropbox – Dropbox

class dropbox.dropbox_client.Dropbox(oauth2_access_token=None, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=None, ca_certs=None)

Bases: dropbox.dropbox_client._DropboxTransport, dropbox.base.DropboxBase

Use this class to make requests to the Dropbox API using a user’s access token. Methods of this class are meant to act on the corresponding user’s Dropbox.

__init__(oauth2_access_token=None, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=None, ca_certs=None)
Parameters:
  • oauth2_access_token (str) – OAuth2 access token for making client requests.
  • max_retries_on_error (int) – On 5xx errors, the number of times to retry.
  • max_retries_on_rate_limit (Optional[int]) – On 429 errors, the number of times to retry. If None, always retries.
  • user_agent (str) – The user agent to use when making requests. This helps us identify requests coming from your application. We recommend you use the format “AppName/Version”. If set, we append “/OfficialDropboxPythonSDKv2/__version__” to the user_agent,
  • session (requests.sessions.Session) – If not provided, a new session (connection pool) is created. To share a session across multiple clients, use create_session().
  • headers (dict) – Additional headers to add to requests.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, client will wait forever. Defaults to 100 seconds.
  • oauth2_refresh_token (str) – OAuth2 refresh token for refreshing access token
  • oauth2_access_token_expiration (datetime) – Expiration for oauth2_access_token
  • app_key (str) – application key of requesting application; used for token refresh
  • app_secret (str) – application secret of requesting application; used for token refresh Not required if PKCE was used to authorize the token
  • scope (list) – list of scopes to request on refresh. If left blank, refresh will request all available scopes for application
  • ca_certs (str) – path to CA certificate. If left blank, default certificate location will be used
account_set_profile_photo(photo)

Sets a user’s profile photo.

Route attributes:
scope: account_info.write
Parameters:photo (dropbox.account.PhotoSourceArg) – Image to set as the user’s new profile photo.
Return type:dropbox.account.SetProfilePhotoResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.account.SetProfilePhotoError
auth_token_from_oauth1(oauth1_token, oauth1_token_secret)

Creates an OAuth 2.0 access token from the supplied OAuth 1.0 access token.

Parameters:
  • oauth1_token (str) – The supplied OAuth 1.0 access token.
  • oauth1_token_secret (str) – The token secret associated with the supplied access token.
Return type:

dropbox.auth.TokenFromOAuth1Result

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.auth.TokenFromOAuth1Error
auth_token_revoke()

Disables the access token used to authenticate the call. If there is a corresponding refresh token for the access token, this disables that refresh token, as well as any other access tokens for that refresh token.

Return type:None
check_and_refresh_access_token()

Checks if access token needs to be refreshed and refreshes if possible :return:

check_app(query='')

This endpoint performs App Authentication, validating the supplied app key and secret, and returns the supplied string, to allow you to test your code and connection to the Dropbox API. It has no other effect. If you receive an HTTP 200 response with the supplied query, it indicates at least part of the Dropbox API infrastructure is working and that the app key and secret valid.

Parameters:query (str) – The string that you’d like to be echoed back to you.
Return type:dropbox.check.EchoResult
check_user(query='')

This endpoint performs User Authentication, validating the supplied access token, and returns the supplied string, to allow you to test your code and connection to the Dropbox API. It has no other effect. If you receive an HTTP 200 response with the supplied query, it indicates at least part of the Dropbox API infrastructure is working and that the access token is valid.

Route attributes:
scope: account_info.read
Parameters:query (str) – The string that you’d like to be echoed back to you.
Return type:dropbox.check.EchoResult
clone(oauth2_access_token=None, max_retries_on_error=None, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=None, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=None)

Creates a new copy of the Dropbox client with the same defaults unless modified by arguments to clone()

See constructor for original parameter descriptions.

Returns:New instance of Dropbox client
Return type:Dropbox
close()

Cleans up all resources like the request session/network connection.

contacts_delete_manual_contacts()

Removes all manually added contacts. You’ll still keep contacts who are on your team or who you imported. New contacts will be added when you share.

Route attributes:
scope: contacts.write
Return type:None
contacts_delete_manual_contacts_batch(email_addresses)

Removes manually added contacts from the given list.

Route attributes:
scope: contacts.write
Parameters:email_addresses (List[str]) – List of manually added contacts to be deleted.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.contacts.DeleteManualContactsError
file_properties_properties_add(path, property_groups)

Add property groups to a Dropbox file. See file_properties_templates_add_for_user() or file_properties_templates_add_for_team() to create new templates.

Route attributes:
scope: files.metadata.write
Parameters:path (str) – A unique identifier for the file or folder.
:param List[dropbox.file_properties.PropertyGroup]
property_groups: The property groups which are to be added to a Dropbox file. No two groups in the input should refer to the same template.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.AddPropertiesError
file_properties_properties_overwrite(path, property_groups)

Overwrite property groups associated with a file. This endpoint should be used instead of file_properties_properties_update() when property groups are being updated via a “snapshot” instead of via a “delta”. In other words, this endpoint will delete all omitted fields from a property group, whereas file_properties_properties_update() will only delete fields that are explicitly marked for deletion.

Route attributes:
scope: files.metadata.write
Parameters:path (str) – A unique identifier for the file or folder.
:param List[dropbox.file_properties.PropertyGroup]
property_groups: The property groups “snapshot” updates to force apply. No two groups in the input should refer to the same template.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.InvalidPropertyGroupError
file_properties_properties_remove(path, property_template_ids)

Permanently removes the specified property group from the file. To remove specific property field key value pairs, see file_properties_properties_update(). To update a template, see file_properties_templates_update_for_user() or file_properties_templates_update_for_team(). To remove a template, see file_properties_templates_remove_for_user() or file_properties_templates_remove_for_team().

Route attributes:
scope: files.metadata.write
Parameters:
  • path (str) – A unique identifier for the file or folder.
  • property_template_ids (List[str]) – A list of identifiers for a template created by file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.file_properties.RemovePropertiesError

Search across property templates for particular property field values.

Route attributes:
scope: files.metadata.read
:param List[dropbox.file_properties.PropertiesSearchQuery]
queries: Queries to search.
Parameters:template_filter (dropbox.file_properties.TemplateFilter) – Filter results to contain only properties associated with these template IDs.
Return type:dropbox.file_properties.PropertiesSearchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.PropertiesSearchError
file_properties_properties_search_continue(cursor)

Once a cursor has been retrieved from file_properties_properties_search(), use this to paginate through all search results.

Route attributes:
scope: files.metadata.read
Parameters:cursor (str) – The cursor returned by your last call to file_properties_properties_search() or file_properties_properties_search_continue().
Return type:dropbox.file_properties.PropertiesSearchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.PropertiesSearchContinueError
file_properties_properties_update(path, update_property_groups)

Add, update or remove properties associated with the supplied file and templates. This endpoint should be used instead of file_properties_properties_overwrite() when property groups are being updated via a “delta” instead of via a “snapshot” . In other words, this endpoint will not delete any omitted fields from a property group, whereas file_properties_properties_overwrite() will delete any fields that are omitted from a property group.

Route attributes:
scope: files.metadata.write
Parameters:path (str) – A unique identifier for the file or folder.
:param List[dropbox.file_properties.PropertyGroupUpdate]
update_property_groups: The property groups “delta” updates to apply.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.UpdatePropertiesError
file_properties_templates_add_for_user(name, description, fields)

Add a template associated with a user. See file_properties_properties_add() to add properties to a file. This endpoint can’t be called on a team member or admin’s behalf.

Route attributes:
scope: files.metadata.write
Return type:dropbox.file_properties.AddTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.ModifyTemplateError
file_properties_templates_get_for_user(template_id)

Get the schema for a specified template. This endpoint can’t be called on a team member or admin’s behalf.

Route attributes:
scope: files.metadata.read
Parameters:template_id (str) – An identifier for template added by route See file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
Return type:dropbox.file_properties.GetTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_list_for_user()

Get the template identifiers for a team. To get the schema of each template use file_properties_templates_get_for_user(). This endpoint can’t be called on a team member or admin’s behalf.

Route attributes:
scope: files.metadata.read
Return type:dropbox.file_properties.ListTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_remove_for_user(template_id)

Permanently removes the specified template created from file_properties_templates_add_for_user(). All properties associated with the template will also be removed. This action cannot be undone.

Route attributes:
scope: files.metadata.write
Parameters:template_id (str) – An identifier for a template created by file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_update_for_user(template_id, name=None, description=None, add_fields=None)

Update a template associated with a user. This route can update the template name, the template description and add optional properties to templates. This endpoint can’t be called on a team member or admin’s behalf.

Route attributes:
scope: files.metadata.write
Parameters:
  • template_id (str) – An identifier for template added by See file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
  • name (Nullable[str]) – A display name for the template. template names can be up to 256 bytes.
  • description (Nullable[str]) – Description for the new template. Template descriptions can be up to 1024 bytes.
:param
Nullable[List[dropbox.file_properties.PropertyFieldTemplate]] add_fields: Property field templates to be added to the group template. There can be up to 32 properties in a single template.
Return type:dropbox.file_properties.UpdateTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.ModifyTemplateError
file_requests_count()

Returns the total number of file requests owned by this user. Includes both open and closed file requests.

Route attributes:
scope: file_requests.read
Return type:dropbox.file_requests.CountFileRequestsResult
file_requests_create(title, destination, deadline=None, open=True, description=None)

Creates a file request for this user.

Route attributes:
scope: file_requests.write
Parameters:
  • title (str) – The title of the file request. Must not be empty.
  • destination (str) – The path of the folder in the Dropbox where uploaded files will be sent. For apps with the app folder permission, this will be relative to the app folder.
:param Nullable[dropbox.file_requests.FileRequestDeadline]
deadline: The deadline for the file request. Deadlines can only be set by Professional and Business accounts.
Parameters:
  • open (bool) – Whether or not the file request should be open. If the file request is closed, it will not accept any file submissions, but it can be opened later.
  • description (Nullable[str]) – A description of the file request.
Return type:

dropbox.file_requests.FileRequest

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.file_requests.CreateFileRequestError
file_requests_delete(ids)

Delete a batch of closed file requests.

Route attributes:
scope: file_requests.write
Parameters:ids (List[str]) – List IDs of the file requests to delete.
Return type:dropbox.file_requests.DeleteFileRequestsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_requests.DeleteFileRequestError
file_requests_delete_all_closed()

Delete all closed file requests owned by this user.

Route attributes:
scope: file_requests.write
Return type:dropbox.file_requests.DeleteAllClosedFileRequestsResult
file_requests_get(id)

Returns the specified file request.

Route attributes:
scope: file_requests.read
Parameters:id (str) – The ID of the file request to retrieve.
Return type:dropbox.file_requests.FileRequest
file_requests_list()

Returns a list of file requests owned by this user. For apps with the app folder permission, this will only return file requests with destinations in the app folder.

Route attributes:
scope: file_requests.read
Return type:dropbox.file_requests.ListFileRequestsResult
file_requests_list_continue(cursor)

Once a cursor has been retrieved from file_requests_list_v2(), use this to paginate through all file requests. The cursor must come from a previous call to file_requests_list_v2() or file_requests_list_continue().

Route attributes:
scope: file_requests.read
Parameters:cursor (str) – The cursor returned by the previous API call specified in the endpoint description.
Return type:dropbox.file_requests.ListFileRequestsV2Result
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_requests.ListFileRequestsContinueError
file_requests_list_v2(limit=1000)

Returns a list of file requests owned by this user. For apps with the app folder permission, this will only return file requests with destinations in the app folder.

Route attributes:
scope: file_requests.read
Parameters:limit (int) – The maximum number of file requests that should be returned per request.
Return type:dropbox.file_requests.ListFileRequestsV2Result
file_requests_update(id, title=None, destination=None, deadline=UpdateFileRequestDeadline(u'no_update', None), open=None, description=None)

Update a file request.

Route attributes:
scope: file_requests.write
Parameters:
  • id (str) – The ID of the file request to update.
  • title (Nullable[str]) – The new title of the file request. Must not be empty.
  • destination (Nullable[str]) – The new path of the folder in the Dropbox where uploaded files will be sent. For apps with the app folder permission, this will be relative to the app folder.
  • deadline (dropbox.file_requests.UpdateFileRequestDeadline) – The new deadline for the file request. Deadlines can only be set by Professional and Business accounts.
  • open (Nullable[bool]) – Whether to set this file request as open or closed.
  • description (Nullable[str]) – The description of the file request.
Return type:

dropbox.file_requests.FileRequest

files_alpha_get_metadata(path, include_media_info=False, include_deleted=False, include_has_explicit_shared_members=False, include_property_groups=None, include_property_templates=None)

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.

Route attributes:
scope: files.metadata.read
Parameters:include_property_templates (Nullable[List[str]]) – If set to a valid list of template IDs, FileMetadata.property_groups is set for files with custom properties.
Return type:dropbox.files.Metadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.AlphaGetMetadataError
files_alpha_upload(f, path, mode=WriteMode(u'add', None), autorename=False, client_modified=None, mute=False, property_groups=None, strict_conflict=False, content_hash=None)

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 files_upload_session_start().

Route attributes:
scope: files.content.write
Parameters:
  • f (bytes) – Contents to upload.
  • content_hash (Nullable[str]) – A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page.
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.UploadError
files_copy(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

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.

Route attributes:
scope: files.content.write
Parameters:
  • allow_shared_folder (bool) – This flag has no effect.
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the file to avoid the conflict.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.Metadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RelocationError
files_copy_batch(entries, autorename=False, allow_shared_folder=False, allow_ownership_transfer=False)

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 files_copy_batch_check() to check the job status.

Route attributes:
scope: files.content.write
Parameters:
  • allow_shared_folder (bool) – This flag has no effect.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.RelocationBatchLaunch

files_copy_batch_check(async_job_id)

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

Route attributes:
scope: files.content.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.RelocationBatchJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_copy_batch_check_v2(async_job_id)

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

Route attributes:
scope: files.content.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.RelocationBatchV2JobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_copy_batch_v2(entries, autorename=False)

Copy multiple files or folders to different locations at once in the user’s Dropbox. This route will replace files_copy_batch(). The main difference is this route will return status for each entry, while files_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 files_copy_batch_check_v2() to check the job status.

Route attributes:
scope: files.content.write
:param List[dropbox.files.RelocationPath] entries: List of
entries to be moved or copied. Each entry is dropbox.files.RelocationPath.
Parameters:autorename (bool) – If there’s a conflict with any file, have the Dropbox server try to autorename that file to avoid the conflict.
Return type:dropbox.files.RelocationBatchV2Launch
files_copy_reference_get(path)

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 files_copy_reference_save().

Route attributes:
scope: files.content.write
Parameters:path (str) – The path to the file or folder you want to get a copy reference to.
Return type:dropbox.files.GetCopyReferenceResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.GetCopyReferenceError
files_copy_reference_save(copy_reference, path)

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

Route attributes:
scope: files.content.write
Parameters:
  • copy_reference (str) – A copy reference returned by files_copy_reference_get().
  • path (str) – Path in the user’s Dropbox that is the destination.
Return type:

dropbox.files.SaveCopyReferenceResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.SaveCopyReferenceError
files_copy_v2(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

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.

Route attributes:
scope: files.content.write
Parameters:
  • allow_shared_folder (bool) – This flag has no effect.
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the file to avoid the conflict.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.RelocationResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RelocationError
files_create_folder(path, autorename=False)

Create a folder at a given path.

Route attributes:
scope: files.content.write
Parameters:
  • path (str) – Path in the user’s Dropbox to create.
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the folder to avoid the conflict.
Return type:

dropbox.files.FolderMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.CreateFolderError
files_create_folder_batch(paths, autorename=False, force_async=False)

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 files_create_folder_batch_check() to check the job status.

Route attributes:
scope: files.content.write
Parameters:
  • paths (List[str]) – List of paths to be created in the user’s Dropbox. Duplicate path arguments in the batch are considered only once.
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the folder to avoid the conflict.
  • force_async (bool) – Whether to force the create to happen asynchronously.
Return type:

dropbox.files.CreateFolderBatchLaunch

files_create_folder_batch_check(async_job_id)

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

Route attributes:
scope: files.content.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.CreateFolderBatchJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_create_folder_v2(path, autorename=False)

Create a folder at a given path.

Route attributes:
scope: files.content.write
Parameters:
  • path (str) – Path in the user’s Dropbox to create.
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the folder to avoid the conflict.
Return type:

dropbox.files.CreateFolderResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.CreateFolderError
files_delete(path, parent_rev=None)

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 dropbox.files.FileMetadata or dropbox.files.FolderMetadata for the item at time of deletion, and not a dropbox.files.DeletedMetadata object.

Route attributes:
scope: files.content.write
Parameters:
  • path (str) – Path in the user’s Dropbox to delete.
  • parent_rev (Nullable[str]) – Perform delete if given “rev” matches the existing file’s latest “rev”. This field does not support deleting a folder.
Return type:

dropbox.files.Metadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DeleteError
files_delete_batch(entries)

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

Route attributes:
scope: files.content.write
Return type:dropbox.files.DeleteBatchLaunch
files_delete_batch_check(async_job_id)

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

Route attributes:
scope: files.content.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.DeleteBatchJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_delete_v2(path, parent_rev=None)

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 dropbox.files.FileMetadata or dropbox.files.FolderMetadata for the item at time of deletion, and not a dropbox.files.DeletedMetadata object.

Route attributes:
scope: files.content.write
Parameters:
  • path (str) – Path in the user’s Dropbox to delete.
  • parent_rev (Nullable[str]) – Perform delete if given “rev” matches the existing file’s latest “rev”. This field does not support deleting a folder.
Return type:

dropbox.files.DeleteResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DeleteError
files_download(path, rev=None)

Download a file from a user’s Dropbox.

Route attributes:
scope: files.content.read
Parameters:
  • path (str) – The path of the file to download.
  • rev (Nullable[str]) – Please specify revision in path instead.
Return type:

(dropbox.files.FileMetadata, requests.models.Response)

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DownloadError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_download_to_file(download_path, path, rev=None)

Download a file from a user’s Dropbox.

Route attributes:
scope: files.content.read
Parameters:
  • download_path (str) – Path on local machine to save file.
  • path (str) – The path of the file to download.
  • rev (Nullable[str]) – Please specify revision in path instead.
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DownloadError
files_download_zip(path)

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.

Route attributes:
scope: files.content.read
Parameters:path (str) – The path of the folder to download.
Return type:(dropbox.files.DownloadZipResult, requests.models.Response)
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.DownloadZipError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_download_zip_to_file(download_path, path)

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.

Route attributes:
scope: files.content.read
Parameters:
  • download_path (str) – Path on local machine to save file.
  • path (str) – The path of the folder to download.
Return type:

dropbox.files.DownloadZipResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DownloadZipError
files_export(path, export_format=None)

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.

Route attributes:
scope: files.content.read
Parameters:
  • path (str) – The path of the file to be exported.
  • export_format (Nullable[str]) – The file format to which the file should be exported. This must be one of the formats listed in the file’s export_options returned by files_get_metadata(). If none is specified, the default format (specified in export_as in file metadata) will be used.
Return type:

(dropbox.files.ExportResult, requests.models.Response)

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ExportError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_export_to_file(download_path, path, export_format=None)

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.

Route attributes:
scope: files.content.read
Parameters:
  • download_path (str) – Path on local machine to save file.
  • path (str) – The path of the file to be exported.
  • export_format (Nullable[str]) – The file format to which the file should be exported. This must be one of the formats listed in the file’s export_options returned by files_get_metadata(). If none is specified, the default format (specified in export_as in file metadata) will be used.
Return type:

dropbox.files.ExportResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ExportError
files_get_file_lock_batch(entries)

Return the lock metadata for the given list of paths.

Route attributes:
scope: files.content.read
:param List[dropbox.files.LockFileArg] entries: List of
‘entries’. Each ‘entry’ contains a path of the file which will be locked or queried. Duplicate path arguments in the batch are considered only once.
Return type:dropbox.files.LockFileBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.LockFileError
files_get_metadata(path, include_media_info=False, include_deleted=False, include_has_explicit_shared_members=False, include_property_groups=None)

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

Route attributes:
scope: files.metadata.read
Parameters:
  • path (str) – The path of a file or folder on Dropbox.
  • include_media_info (bool) – If true, FileMetadata.media_info is set for photo and video.
  • include_deleted (bool) – If true, dropbox.files.DeletedMetadata will be returned for deleted file or folder, otherwise LookupError.not_found will be returned.
  • include_has_explicit_shared_members (bool) – If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
:param Nullable[dropbox.files.TemplateFilterBase]
include_property_groups: If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates.
Return type:dropbox.files.Metadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.GetMetadataError
files_get_preview(path, rev=None)

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.

Route attributes:
scope: files.content.read
Parameters:
  • path (str) – The path of the file to preview.
  • rev (Nullable[str]) – Please specify revision in path instead.
Return type:

(dropbox.files.FileMetadata, requests.models.Response)

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.PreviewError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_get_preview_to_file(download_path, path, rev=None)

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.

Route attributes:
scope: files.content.read
Parameters:
  • download_path (str) – Path on local machine to save file.
  • path (str) – The path of the file to preview.
  • rev (Nullable[str]) – Please specify revision in path instead.
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.PreviewError

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.

Route attributes:
scope: files.content.read
Parameters:path (str) – The path to the file you want a temporary link to.
Return type:dropbox.files.GetTemporaryLinkResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.GetTemporaryLinkError

Get a one-time use temporary upload link to upload a file to a Dropbox location. This endpoint acts as a delayed files_upload(). The returned temporary upload link may be used to make a POST request with the data to be uploaded. The upload will then be perfomed with the dropbox.files.CommitInfo previously provided to files_get_temporary_upload_link() but evaluated only upon consumption. Hence, errors stemming from invalid dropbox.files.CommitInfo with respect to the state of the user’s Dropbox will only be communicated at consumption time. Additionally, these errors are surfaced as generic HTTP 409 Conflict responses, potentially hiding issue details. The maximum temporary upload link duration is 4 hours. Upon consumption or expiration, a new link will have to be generated. Multiple links may exist for a specific upload path at any given time. The POST request on the temporary upload link must have its Content-Type set to “application/octet-stream”. Example temporary upload link consumption request: curl -X POST https://content.dropboxapi.com/apitul/1/bNi2uIYF51cVBND –header “Content-Type: application/octet-stream” –data-binary @local_file.txt A successful temporary upload link consumption request returns the content hash of the uploaded data in JSON format. Example successful temporary upload link consumption response: {“content-hash”: “599d71033d700ac892a0e48fa61b125d2f5994”} An unsuccessful temporary upload link consumption request returns any of the following status codes: HTTP 400 Bad Request: Content-Type is not one of application/octet-stream and text/plain or request is invalid. HTTP 409 Conflict: The temporary upload link does not exist or is currently unavailable, the upload failed, or another error happened. HTTP 410 Gone: The temporary upload link is expired or consumed. Example unsuccessful temporary upload link consumption response: Temporary upload link has been recently consumed.

Route attributes:
scope: files.content.write
Parameters:
  • commit_info (dropbox.files.CommitInfo) – Contains the path and other optional modifiers for the future upload commit. Equivalent to the parameters provided to files_upload().
  • duration (float) – How long before this link expires, in seconds. Attempting to start an upload with this link longer than this period of time after link creation will result in an error.
Return type:

dropbox.files.GetTemporaryUploadLinkResult

files_get_thumbnail(path, format=ThumbnailFormat(u'jpeg', None), size=ThumbnailSize(u'w64h64', None), mode=ThumbnailMode(u'strict', None))

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.

Route attributes:
scope: files.content.read
Parameters:
  • path (str) – The path to the image file you want to thumbnail.
  • format (dropbox.files.ThumbnailFormat) – The format for the thumbnail image, jpeg (default) or png. For images that are photos, jpeg should be preferred, while png is better for screenshots and digital arts.
  • size (dropbox.files.ThumbnailSize) – The size for the thumbnail image.
  • mode (dropbox.files.ThumbnailMode) – How to resize and crop the image to achieve the desired size.
Return type:

(dropbox.files.FileMetadata, requests.models.Response)

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ThumbnailError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_get_thumbnail_batch(entries)

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.

Route attributes:
scope: files.content.read
:param List[dropbox.files.ThumbnailArg] entries: List of files
to get thumbnails.
Return type:dropbox.files.GetThumbnailBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.GetThumbnailBatchError
files_get_thumbnail_to_file(download_path, path, format=ThumbnailFormat(u'jpeg', None), size=ThumbnailSize(u'w64h64', None), mode=ThumbnailMode(u'strict', None))

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.

Route attributes:
scope: files.content.read
Parameters:
  • download_path (str) – Path on local machine to save file.
  • path (str) – The path to the image file you want to thumbnail.
  • format (dropbox.files.ThumbnailFormat) – The format for the thumbnail image, jpeg (default) or png. For images that are photos, jpeg should be preferred, while png is better for screenshots and digital arts.
  • size (dropbox.files.ThumbnailSize) – The size for the thumbnail image.
  • mode (dropbox.files.ThumbnailMode) – How to resize and crop the image to achieve the desired size.
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ThumbnailError
files_get_thumbnail_to_file_v2(download_path, resource, format=ThumbnailFormat(u'jpeg', None), size=ThumbnailSize(u'w64h64', None), mode=ThumbnailMode(u'strict', None))

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.

Route attributes:
scope: files.content.read
Parameters:
  • download_path (str) – Path on local machine to save file.
  • resource (dropbox.files.PathOrLink) – Information specifying which file to preview. This could be a path to a file, a shared link pointing to a file, or a shared link pointing to a folder, with a relative path.
  • format (dropbox.files.ThumbnailFormat) – The format for the thumbnail image, jpeg (default) or png. For images that are photos, jpeg should be preferred, while png is better for screenshots and digital arts.
  • size (dropbox.files.ThumbnailSize) – The size for the thumbnail image.
  • mode (dropbox.files.ThumbnailMode) – How to resize and crop the image to achieve the desired size.
Return type:

dropbox.files.PreviewResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ThumbnailV2Error
files_get_thumbnail_v2(resource, format=ThumbnailFormat(u'jpeg', None), size=ThumbnailSize(u'w64h64', None), mode=ThumbnailMode(u'strict', None))

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.

Route attributes:
scope: files.content.read
Parameters:
  • resource (dropbox.files.PathOrLink) – Information specifying which file to preview. This could be a path to a file, a shared link pointing to a file, or a shared link pointing to a folder, with a relative path.
  • format (dropbox.files.ThumbnailFormat) – The format for the thumbnail image, jpeg (default) or png. For images that are photos, jpeg should be preferred, while png is better for screenshots and digital arts.
  • size (dropbox.files.ThumbnailSize) – The size for the thumbnail image.
  • mode (dropbox.files.ThumbnailMode) – How to resize and crop the image to achieve the desired size.
Return type:

(dropbox.files.PreviewResult, requests.models.Response)

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ThumbnailV2Error

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

files_list_folder(path, recursive=False, include_media_info=False, include_deleted=False, include_has_explicit_shared_members=False, include_mounted_folders=True, limit=None, shared_link=None, include_property_groups=None, include_non_downloadable_files=True)

Starts returning the contents of a folder. If the result’s ListFolderResult.has_more field is True, call files_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 dropbox.files.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 dropbox.files.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 dropbox.files.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: dropbox.auth.RateLimitError may be returned if multiple files_list_folder() or files_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.

Route attributes:
scope: files.metadata.read
Parameters:
  • path (str) – A unique identifier for the file.
  • recursive (bool) – If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders.
  • include_media_info (bool) – If true, FileMetadata.media_info is set for photo and video. This parameter will no longer have an effect starting December 2, 2019.
  • include_deleted (bool) – If true, the results will include entries for files and folders that used to exist but were deleted.
  • include_has_explicit_shared_members (bool) – If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
  • include_mounted_folders (bool) – If true, the results will include entries under mounted folders which includes app folder, shared folder and team folder.
  • limit (Nullable[int]) – The maximum number of results to return per request. Note: This is an approximate number and there can be slightly more entries returned in some cases.
:param Nullable[dropbox.files.SharedLink] shared_link: A shared
link to list the contents of. If the link is password-protected, the password must be provided. If this field is present, ListFolderArg.path will be relative to root of the shared link. Only non-recursive mode is supported for shared link.
:param Nullable[dropbox.files.TemplateFilterBase]
include_property_groups: If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates.
Parameters:include_non_downloadable_files (bool) – If true, include files that are not downloadable, i.e. Google Docs.
Return type:dropbox.files.ListFolderResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.ListFolderError
files_list_folder_continue(cursor)

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

Route attributes:
scope: files.metadata.read
Parameters:cursor (str) – The cursor returned by your last call to files_list_folder() or files_list_folder_continue().
Return type:dropbox.files.ListFolderResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.ListFolderContinueError
files_list_folder_get_latest_cursor(path, recursive=False, include_media_info=False, include_deleted=False, include_has_explicit_shared_members=False, include_mounted_folders=True, limit=None, shared_link=None, include_property_groups=None, include_non_downloadable_files=True)

A way to quickly get a cursor for the folder’s state. Unlike files_list_folder(), files_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.

Route attributes:
scope: files.metadata.read
Parameters:
  • path (str) – A unique identifier for the file.
  • recursive (bool) – If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders.
  • include_media_info (bool) – If true, FileMetadata.media_info is set for photo and video. This parameter will no longer have an effect starting December 2, 2019.
  • include_deleted (bool) – If true, the results will include entries for files and folders that used to exist but were deleted.
  • include_has_explicit_shared_members (bool) – If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
  • include_mounted_folders (bool) – If true, the results will include entries under mounted folders which includes app folder, shared folder and team folder.
  • limit (Nullable[int]) – The maximum number of results to return per request. Note: This is an approximate number and there can be slightly more entries returned in some cases.
:param Nullable[dropbox.files.SharedLink] shared_link: A shared
link to list the contents of. If the link is password-protected, the password must be provided. If this field is present, ListFolderArg.path will be relative to root of the shared link. Only non-recursive mode is supported for shared link.
:param Nullable[dropbox.files.TemplateFilterBase]
include_property_groups: If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates.
Parameters:include_non_downloadable_files (bool) – If true, include files that are not downloadable, i.e. Google Docs.
Return type:dropbox.files.ListFolderGetLatestCursorResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.ListFolderError
files_list_folder_longpoll(cursor, timeout=30)

A longpoll endpoint to wait for changes on an account. In conjunction with files_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.

Route attributes:
scope: files.metadata.read
Parameters:
  • cursor (str) – A cursor as returned by files_list_folder() or files_list_folder_continue(). Cursors retrieved by setting ListFolderArg.include_media_info to True are not supported.
  • timeout (int) – A timeout in seconds. The request will block for at most this length of time, plus up to 90 seconds of random jitter added to avoid the thundering herd problem. Care should be taken when using this parameter, as some network infrastructure does not support long timeouts.
Return type:

dropbox.files.ListFolderLongpollResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ListFolderLongpollError
files_list_revisions(path, mode=ListRevisionsMode(u'path', None), limit=10)

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.

Route attributes:
scope: files.metadata.read
Parameters:
  • path (str) – The path to the file you want to see the revisions of.
  • mode (dropbox.files.ListRevisionsMode) – Determines the behavior of the API in listing the revisions for a given file path or id.
  • limit (int) – The maximum number of revision entries returned.
Return type:

dropbox.files.ListRevisionsResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.ListRevisionsError
files_lock_file_batch(entries)

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.

Route attributes:
scope: files.content.write
:param List[dropbox.files.LockFileArg] entries: List of
‘entries’. Each ‘entry’ contains a path of the file which will be locked or queried. Duplicate path arguments in the batch are considered only once.
Return type:dropbox.files.LockFileBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.LockFileError
files_move(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

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.

Route attributes:
scope: files.content.write
Parameters:
  • allow_shared_folder (bool) – This flag has no effect.
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the file to avoid the conflict.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.Metadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RelocationError
files_move_batch(entries, autorename=False, allow_shared_folder=False, allow_ownership_transfer=False)

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 files_move_batch_check() to check the job status.

Route attributes:
scope: files.content.write
Parameters:
  • allow_shared_folder (bool) – This flag has no effect.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.RelocationBatchLaunch

files_move_batch_check(async_job_id)

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

Route attributes:
scope: files.content.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.RelocationBatchJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_move_batch_check_v2(async_job_id)

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

Route attributes:
scope: files.content.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.RelocationBatchV2JobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_move_batch_v2(entries, autorename=False, allow_ownership_transfer=False)

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 files_move_batch(). The main difference is this route will return status for each entry, while files_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 files_move_batch_check_v2() to check the job status.

Route attributes:
scope: files.content.write
Parameters:allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:dropbox.files.RelocationBatchV2Launch
files_move_v2(from_path, to_path, allow_shared_folder=False, autorename=False, allow_ownership_transfer=False)

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.

Route attributes:
scope: files.content.write
Parameters:
  • allow_shared_folder (bool) – This flag has no effect.
  • autorename (bool) – If there’s a conflict, have the Dropbox server try to autorename the file to avoid the conflict.
  • allow_ownership_transfer (bool) – Allow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies.
Return type:

dropbox.files.RelocationResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RelocationError
files_paper_create(f, path, import_format)

Creates a new Paper doc with the provided content.

Route attributes:
scope: files.content.write
Parameters:
  • f (bytes) – Contents to upload.
  • path (str) – The fully qualified path to the location in the user’s Dropbox where the Paper Doc should be created. This should include the document’s title and end with .paper.
  • import_format (dropbox.files.ImportFormat) – The format of the provided data.
Return type:

dropbox.files.PaperCreateResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.PaperCreateError
files_paper_update(f, path, import_format, doc_update_policy, paper_revision=None)

Updates an existing Paper doc with the provided content.

Route attributes:
scope: files.content.write
Parameters:
  • f (bytes) – Contents to upload.
  • path (str) – Path in the user’s Dropbox to update. The path must correspond to a Paper doc or an error will be returned.
  • import_format (dropbox.files.ImportFormat) – The format of the provided data.
  • doc_update_policy (dropbox.files.PaperDocUpdatePolicy) – How the provided content should be applied to the doc.
  • paper_revision (Nullable[int]) – The latest doc revision. Required when doc_update_policy is update. This value must match the current revision of the doc or error revision_mismatch will be returned.
Return type:

dropbox.files.PaperUpdateResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.PaperUpdateError
files_permanently_delete(path, parent_rev=None)

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.

Route attributes:
scope: files.permanent_delete
Parameters:
  • path (str) – Path in the user’s Dropbox to delete.
  • parent_rev (Nullable[str]) – Perform delete if given “rev” matches the existing file’s latest “rev”. This field does not support deleting a folder.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.DeleteError
files_properties_add(path, property_groups)
Route attributes:
scope: files.metadata.write
Parameters:path (str) – A unique identifier for the file or folder.
:param List[dropbox.files.PropertyGroup] property_groups: The
property groups which are to be added to a Dropbox file. No two groups in the input should refer to the same template.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.AddPropertiesError
files_properties_overwrite(path, property_groups)
Route attributes:
scope: files.metadata.write
Parameters:path (str) – A unique identifier for the file or folder.
:param List[dropbox.files.PropertyGroup] property_groups: The
property groups “snapshot” updates to force apply. No two groups in the input should refer to the same template.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.InvalidPropertyGroupError
files_properties_remove(path, property_template_ids)
Route attributes:
scope: files.metadata.write
Parameters:
  • path (str) – A unique identifier for the file or folder.
  • property_template_ids (List[str]) – A list of identifiers for a template created by files_templates_add_for_user() or files_templates_add_for_team().
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RemovePropertiesError
files_properties_template_get(template_id)
Route attributes:
scope: files.metadata.read
Parameters:template_id (str) – An identifier for template added by route See files_templates_add_for_user() or files_templates_add_for_team().
Return type:dropbox.files.GetTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.TemplateError
files_properties_template_list()
Route attributes:
scope: files.metadata.read
Return type:dropbox.files.ListTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.TemplateError
files_properties_update(path, update_property_groups)
Route attributes:
scope: files.metadata.write
Parameters:path (str) – A unique identifier for the file or folder.
:param List[dropbox.files.PropertyGroupUpdate]
update_property_groups: The property groups “delta” updates to apply.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.UpdatePropertiesError
files_restore(path, rev)

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

Route attributes:
scope: files.content.write
Parameters:
  • path (str) – The path to save the restored file.
  • rev (str) – The revision to restore.
Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RestoreError
files_save_url(path, 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).

Route attributes:
scope: files.content.write
Parameters:
  • path (str) – The path in Dropbox where the URL will be saved to.
  • url (str) – The URL to be saved.
Return type:

dropbox.files.SaveUrlResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.SaveUrlError
files_save_url_check_job_status(async_job_id)

Check the status of a files_save_url() job.

Route attributes:
scope: files.content.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.SaveUrlJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError

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.

Route attributes:
scope: files.metadata.read
Parameters:
  • path (str) – The path in the user’s Dropbox to search. Should probably be a folder.
  • query (str) – The string to search for. Query string may be rewritten to improve relevance of results. The string is split on spaces into multiple tokens. For file name searching, the last token is used for prefix matching (i.e. “bat c” matches “bat cave” but not “batman car”).
  • start (int) – The starting index within the search results (used for paging).
  • max_results (int) – The maximum number of search results to return.
  • mode (dropbox.files.SearchMode) – The search mode (filename, filename_and_content, or deleted_filename). Note that searching file content is only available for Dropbox Business accounts.
Return type:

dropbox.files.SearchResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.SearchError
files_search_continue_v2(cursor)

Fetches the next page of search results returned from files_search_v2(). Note: files_search_v2() along with files_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.

Route attributes:
scope: files.metadata.read
Parameters:cursor (str) – The cursor returned by your last call to files_search_v2(). Used to fetch the next page of results.
Return type:dropbox.files.SearchV2Result
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.SearchError
files_search_v2(query, options=None, match_field_options=None, include_highlights=None)

Searches for files and folders. Note: files_search_v2() along with files_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.

Route attributes:
scope: files.metadata.read
Parameters:query (str) – The string to search for. May match across multiple fields based on the request arguments.
:param Nullable[dropbox.files.SearchOptions] options: Options
for more targeted search results.
:param Nullable[dropbox.files.SearchMatchFieldOptions]
match_field_options: Options for search results match fields.
Parameters:include_highlights (Nullable[bool]) – Deprecated and moved this option to SearchMatchFieldOptions.
Return type:dropbox.files.SearchV2Result
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.SearchError
files_tags_add(path, tag_text)

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.

Route attributes:
scope: files.metadata.write
Parameters:
  • path (str) – Path to the item to be tagged.
  • tag_text (str) – The value of the tag to add. Will be automatically converted to lowercase letters.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.AddTagError
files_tags_get(paths)

Get list of tags assigned to items.

Route attributes:
scope: files.metadata.read
Parameters:paths (List[str]) – Path to the items.
Return type:dropbox.files.GetTagsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.BaseTagError
files_tags_remove(path, tag_text)

Remove a tag from an item.

Route attributes:
scope: files.metadata.write
Parameters:
  • path (str) – Path to the item to tag.
  • tag_text (str) – The tag to remove. Will be automatically converted to lowercase letters.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.RemoveTagError
files_unlock_file_batch(entries)

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.

Route attributes:
scope: files.content.write
:param List[dropbox.files.UnlockFileArg] entries: List of
‘entries’. Each ‘entry’ contains a path of the file which will be unlocked. Duplicate path arguments in the batch are considered only once.
Return type:dropbox.files.LockFileBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.LockFileError
files_upload(f, path, mode=WriteMode(u'add', None), autorename=False, client_modified=None, mute=False, property_groups=None, strict_conflict=False, content_hash=None)

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 files_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.

Route attributes:
scope: files.content.write
Parameters:
  • f (bytes) – Contents to upload.
  • content_hash (Nullable[str]) –

    A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page.

Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.UploadError
files_upload_session_append(f, session_id, offset)

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.

Route attributes:
scope: files.content.write
Parameters:
  • f (bytes) – Contents to upload.
  • session_id (str) – The upload session ID (returned by files_upload_session_start()).
  • offset (int) – Offset in bytes at which data should be appended. We use this to make sure upload data isn’t lost or duplicated in the event of a network error.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.UploadSessionAppendError
files_upload_session_append_v2(f, cursor, close=False, content_hash=None)

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.

Route attributes:
scope: files.content.write
Parameters:
  • f (bytes) – Contents to upload.
  • cursor (dropbox.files.UploadSessionCursor) – Contains the upload session ID and the offset.
  • close (bool) – If true, the current session will be closed, at which point you won’t be able to call files_upload_session_append_v2() anymore with the current session.
  • content_hash (Nullable[str]) –

    A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page.

Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.UploadSessionAppendError
files_upload_session_finish(f, cursor, commit, content_hash=None)

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.

Route attributes:
scope: files.content.write
Parameters:
  • f (bytes) – Contents to upload.
  • cursor (dropbox.files.UploadSessionCursor) – Contains the upload session ID and the offset.
  • commit (dropbox.files.CommitInfo) – Contains the path and other optional modifiers for the commit.
  • content_hash (Nullable[str]) –

    A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page.

Return type:

dropbox.files.FileMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.files.UploadSessionFinishError
files_upload_session_finish_batch(entries)

This route helps you commit many files at once into a user’s Dropbox. Use files_upload_session_start() and files_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 files_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 files_upload_session_start() or files_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 files_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.

Route attributes:
scope: files.content.write
:param List[dropbox.files.UploadSessionFinishArg] entries:
Commit information for each file in the batch.
Return type:dropbox.files.UploadSessionFinishBatchLaunch
files_upload_session_finish_batch_check(async_job_id)

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

Route attributes:
scope: files.content.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.files.UploadSessionFinishBatchJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.PollError
files_upload_session_finish_batch_v2(entries)

This route helps you commit many files at once into a user’s Dropbox. Use files_upload_session_start() and files_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 files_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 files_upload_session_start() or files_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.

Route attributes:
scope: files.content.write
:param List[dropbox.files.UploadSessionFinishArg] entries:
Commit information for each file in the batch.
Return type:dropbox.files.UploadSessionFinishBatchResult
files_upload_session_start(f, close=False, session_type=None, content_hash=None)

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 files_upload_session_append_v2() to add more data and files_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 files_upload_session_append_v2() or files_upload_session_finish() more than 7 days after its creation will return a UploadSessionLookupError.not_found. 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 files_upload_session_start(), files_upload_session_append_v2(), files_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 files_upload_session_append_v2() requests. Finally finish the session with files_upload_session_finish(). There are couple of constraints with concurrent sessions to make them work. You can not send data with files_upload_session_start() or files_upload_session_finish() call, only with files_upload_session_append_v2() call. Also data uploaded in files_upload_session_append_v2() call must be multiple of 4194304 bytes (except for last files_upload_session_append_v2() with UploadSessionStartArg.close to True, that may contain any remaining data).

Route attributes:
scope: files.content.write
Parameters:
  • f (bytes) – Contents to upload.
  • close (bool) – If true, the current session will be closed, at which point you won’t be able to call files_upload_session_append_v2() anymore with the current session.
:param Nullable[dropbox.files.UploadSessionType] session_type:
Type of upload session you want to start. If not specified, default is UploadSessionType.sequential.
Parameters:content_hash (Nullable[str]) –

A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page.

Return type:dropbox.files.UploadSessionStartResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.files.UploadSessionStartError
files_upload_session_start_batch(num_sessions, session_type=None)

This route starts batch of upload_sessions. Please refer to upload_session/start usage. 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.

Route attributes:
scope: files.content.write
:param Nullable[dropbox.files.UploadSessionType] session_type:
Type of upload session you want to start. If not specified, default is UploadSessionType.sequential.
Parameters:num_sessions (int) – The number of upload sessions to start.
Return type:dropbox.files.UploadSessionStartBatchResult
openid_userinfo()

This route is used for refreshing the info that is found in the id_token during the OIDC flow. This route doesn’t require any arguments and will use the scopes approved for the given access token.

Route attributes:
scope: openid
Return type:dropbox.openid.UserInfoResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.openid.UserInfoError
paper_docs_archive(doc_id)

Marks the given Paper doc as archived. This action can be performed or undone by anyone with edit permissions to the doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. This endpoint will be retired in September 2020. Refer to the Paper Migration Guide for more information.

Route attributes:
scope: files.content.write
Parameters:doc_id (str) – The Paper doc ID.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_create(f, import_format, parent_folder_id=None)

Creates a new Paper doc with the provided content. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. This endpoint will be retired in September 2020. Refer to the Paper Migration Guide for more information.

Route attributes:
scope: files.content.write
Parameters:
  • f (bytes) – Contents to upload.
  • parent_folder_id (Nullable[str]) – The Paper folder ID where the Paper document should be created. The API user has to have write access to this folder or error is thrown.
  • import_format (dropbox.paper.ImportFormat) – The format of provided data.
Return type:

dropbox.paper.PaperDocCreateUpdateResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.paper.PaperDocCreateError
paper_docs_download(doc_id, export_format)

Exports and downloads Paper doc either as HTML or markdown. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: files.content.read
Return type:(dropbox.paper.PaperDocExportResult, requests.models.Response)
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

paper_docs_download_to_file(download_path, doc_id, export_format)

Exports and downloads Paper doc either as HTML or markdown. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: files.content.read
Parameters:download_path (str) – Path on local machine to save file.
Return type:dropbox.paper.PaperDocExportResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_folder_users_list(doc_id, limit=1000)

Lists the users who are explicitly invited to the Paper folder in which the Paper doc is contained. For private folders all users (including owner) shared on the folder are listed and for team folders all non-team users shared on the folder are returned. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: sharing.read
Parameters:limit (int) – Size limit per batch. The maximum number of users that can be retrieved per batch is 1000. Higher value results in invalid arguments error.
Return type:dropbox.paper.ListUsersOnFolderResponse
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_folder_users_list_continue(doc_id, cursor)

Once a cursor has been retrieved from paper_docs_folder_users_list(), use this to paginate through all users on the Paper folder. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: sharing.read
Parameters:cursor (str) – The cursor obtained from paper_docs_folder_users_list() or paper_docs_folder_users_list_continue(). Allows for pagination.
Return type:dropbox.paper.ListUsersOnFolderResponse
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.ListUsersCursorError
paper_docs_get_folder_info(doc_id)

Retrieves folder information for the given Paper doc. This includes: - folder sharing policy; permissions for subfolders are set by the top-level folder. - full ‘filepath’, i.e. the list of folders (both folderId and folderName) from the root folder to the folder directly containing the Paper doc. If the Paper doc is not in any folder (aka unfiled) the response will be empty. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: sharing.read
Parameters:doc_id (str) – The Paper doc ID.
Return type:dropbox.paper.FoldersContainingPaperDoc
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_list(filter_by=ListPaperDocsFilterBy(u'docs_accessed', None), sort_by=ListPaperDocsSortBy(u'accessed', None), sort_order=ListPaperDocsSortOrder(u'ascending', None), limit=1000)

Return the list of all Paper docs according to the argument specifications. To iterate over through the full pagination, pass the cursor to paper_docs_list_continue(). Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: files.metadata.read
Parameters:
Return type:

dropbox.paper.ListPaperDocsResponse

paper_docs_list_continue(cursor)

Once a cursor has been retrieved from paper_docs_list(), use this to paginate through all Paper doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: files.metadata.read
Parameters:cursor (str) – The cursor obtained from paper_docs_list() or paper_docs_list_continue(). Allows for pagination.
Return type:dropbox.paper.ListPaperDocsResponse
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.ListDocsCursorError
paper_docs_permanently_delete(doc_id)

Permanently deletes the given Paper doc. This operation is final as the doc cannot be recovered. This action can be performed only by the doc owner. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: files.permanent_delete
Parameters:doc_id (str) – The Paper doc ID.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_sharing_policy_get(doc_id)

Gets the default sharing policy for the given Paper doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: sharing.read
Parameters:doc_id (str) – The Paper doc ID.
Return type:dropbox.paper.SharingPolicy
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_sharing_policy_set(doc_id, sharing_policy)

Sets the default sharing policy for the given Paper doc. The default ‘team_sharing_policy’ can be changed only by teams, omit this field for personal accounts. The ‘public_sharing_policy’ policy can’t be set to the value ‘disabled’ because this setting can be changed only via the team admin console. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: sharing.write
Parameters:sharing_policy (dropbox.paper.SharingPolicy) – The default sharing policy to be set for the Paper doc.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_update(f, doc_id, doc_update_policy, revision, import_format)

Updates an existing Paper doc with the provided content. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. This endpoint will be retired in September 2020. Refer to the Paper Migration Guide for more information.

Route attributes:
scope: files.content.write
Parameters:
  • f (bytes) – Contents to upload.
  • doc_update_policy (dropbox.paper.PaperDocUpdatePolicy) – The policy used for the current update call.
  • revision (int) – The latest doc revision. This value must match the head revision or an error code will be returned. This is to prevent colliding writes.
  • import_format (dropbox.paper.ImportFormat) – The format of provided data.
Return type:

dropbox.paper.PaperDocCreateUpdateResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.paper.PaperDocUpdateError
paper_docs_users_add(doc_id, members, custom_message=None, quiet=False)

Allows an owner or editor to add users to a Paper doc or change their permissions using their email address or Dropbox account ID. The doc owner’s permissions cannot be changed. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: sharing.write
:param List[dropbox.paper.AddMember] members: User which should
be added to the Paper doc. Specify only email address or Dropbox account ID.
Parameters:
  • custom_message (Nullable[str]) – A personal message that will be emailed to each successfully added member.
  • quiet (bool) – Clients should set this to true if no email message shall be sent to added users.
Return type:

List[dropbox.paper.AddPaperDocUserMemberResult]

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_users_list(doc_id, limit=1000, filter_by=UserOnPaperDocFilter(u'shared', None))

Lists all users who visited the Paper doc or users with explicit access. This call excludes users who have been removed. The list is sorted by the date of the visit or the share date. The list will include both users, the explicitly shared ones as well as those who came in using the Paper url link. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: sharing.read
Parameters:
  • limit (int) – Size limit per batch. The maximum number of users that can be retrieved per batch is 1000. Higher value results in invalid arguments error.
  • filter_by (dropbox.paper.UserOnPaperDocFilter) – Specify this attribute if you want to obtain users that have already accessed the Paper doc.
Return type:

dropbox.paper.ListUsersOnPaperDocResponse

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_docs_users_list_continue(doc_id, cursor)

Once a cursor has been retrieved from paper_docs_users_list(), use this to paginate through all users on the Paper doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: sharing.read
Parameters:cursor (str) – The cursor obtained from paper_docs_users_list() or paper_docs_users_list_continue(). Allows for pagination.
Return type:dropbox.paper.ListUsersOnPaperDocResponse
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.ListUsersCursorError
paper_docs_users_remove(doc_id, member)

Allows an owner or editor to remove users from a Paper doc using their email address or Dropbox account ID. The doc owner cannot be removed. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: sharing.write
Parameters:member (dropbox.paper.MemberSelector) – User which should be removed from the Paper doc. Specify only email address or Dropbox account ID.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.paper.DocLookupError
paper_folders_create(name, parent_folder_id=None, is_team_folder=None)

Create a new Paper folder with the provided info. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

Route attributes:
scope: files.content.write
Parameters:
  • name (str) – The name of the new Paper folder.
  • parent_folder_id (Nullable[str]) – The encrypted Paper folder Id where the new Paper folder should be created. The API user has to have write access to this folder or error is thrown. If not supplied, the new folder will be created at top level.
  • is_team_folder (Nullable[bool]) – Whether the folder to be created should be a team folder. This value will be ignored if parent_folder_id is supplied, as the new folder will inherit the type (private or team folder) from its parent. We will by default create a top-level private folder if both parent_folder_id and is_team_folder are not supplied.
Return type:

dropbox.paper.PaperFolderCreateResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.paper.PaperFolderCreateError
raise_dropbox_error_for_resp(res)

Checks for errors from a res and handles appropiately.

Parameters:res – Response of an api request.
refresh_access_token(host='api.dropboxapi.com', scope=None)

Refreshes an access token via refresh token if available

Parameters:
  • host – host to hit token endpoint with
  • scope – list of permission scopes for access token
Returns:

request(route, namespace, request_arg, request_binary, timeout=None)

Makes a request to the Dropbox API and in the process validates that the route argument and result are the expected data types. The request_arg is converted to JSON based on the arg_data_type. Likewise, the response is deserialized from JSON and converted to an object based on the {result,error}_data_type.

Parameters:
  • host – The Dropbox API host to connect to.
  • route (stone.backends.python_rsrc.stone_base.Route) – The route to make the request to.
  • request_arg – Argument for the route that conforms to the validator specified by route.arg_type.
  • request_binary – String or file pointer representing the binary payload. Use None if there is no binary payload.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, will use default timeout set on Dropbox object. Defaults to None.
Returns:

The route’s result.

request_json_object(host, route_name, route_style, request_arg, auth_type, request_binary, timeout=None)

Makes a request to the Dropbox API, taking a JSON-serializable Python object as an argument, and returning one as a response.

Parameters:
  • host – The Dropbox API host to connect to.
  • route_name – The name of the route to invoke.
  • route_style – The style of the route.
  • request_arg (str) – A JSON-serializable Python object representing the argument for the route.

:param auth_type str :param Optional[bytes] request_binary: Bytes representing the binary

payload. Use None if there is no binary payload.
Parameters:timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, will use default timeout set on Dropbox object. Defaults to None.
Returns:The route’s result as a JSON-serializable Python object.
request_json_string(host, func_name, route_style, request_json_arg, auth_type, request_binary, timeout=None)

See request_json_string_with_retry() for description of parameters.

request_json_string_with_retry(host, route_name, route_style, request_json_arg, auth_type, request_binary, timeout=None)

See request_json_object() for description of parameters.

Parameters:request_json_arg – A string representing the serialized JSON argument to the route.
sharing_add_file_member(file, members, custom_message=None, quiet=False, access_level=AccessLevel(u'viewer', None), add_message_as_comment=False)

Adds specified members to a file.

Route attributes:
scope: sharing.write
Parameters:file (str) – File to which to add members.
:param List[dropbox.sharing.MemberSelector] members: Members to
add. Note that even an email address is given, this may result in a user being directly added to the membership if that email is the user’s main account email.
Parameters:
  • custom_message (Nullable[str]) – Message to send to added members in their invitation.
  • quiet (bool) – Whether added members should be notified via email and device notifications of their invitation.
  • access_level (dropbox.sharing.AccessLevel) – AccessLevel union object, describing what access level we want to give new members.
  • add_message_as_comment (bool) – If the custom message should be added as a comment on the file.
Return type:

List[dropbox.sharing.FileMemberActionResult]

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.AddFileMemberError
sharing_add_folder_member(shared_folder_id, members, quiet=False, custom_message=None)

Allows an owner or editor (if the ACL update policy allows) of a shared folder to add another member. For the new member to get access to all the functionality for this folder, you will need to call sharing_mount_folder() on their behalf.

Route attributes:
scope: sharing.write
Parameters:shared_folder_id (str) – The ID for the shared folder.
:param List[dropbox.sharing.AddMember] members: The intended
list of members to add. Added members will receive invites to join the shared folder.
Parameters:
  • quiet (bool) – Whether added members should be notified via email and device notifications of their invite.
  • custom_message (Nullable[str]) – Optional message to display to added members in their invitation.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.AddFolderMemberError
sharing_check_job_status(async_job_id)

Returns the status of an asynchronous job.

Route attributes:
scope: sharing.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.sharing.JobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.PollError
sharing_check_remove_member_job_status(async_job_id)

Returns the status of an asynchronous job for sharing a folder.

Route attributes:
scope: sharing.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.sharing.RemoveMemberJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.PollError
sharing_check_share_job_status(async_job_id)

Returns the status of an asynchronous job for sharing a folder.

Route attributes:
scope: sharing.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.sharing.ShareFolderJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.PollError

Create a shared link. If a shared link already exists for the given path, that link is returned. Previously, it was technically possible to break a shared link by moving or renaming the corresponding file or folder. In the future, this will no longer be the case, so your app shouldn’t rely on this behavior. Instead, if your app needs to revoke a shared link, use sharing_revoke_shared_link().

Route attributes:
scope: sharing.write
Parameters:path (str) – The path to share.
:param Nullable[dropbox.sharing.PendingUploadMode]
pending_upload: If it’s okay to share a path that does not yet exist, set this to either PendingUploadMode.file or PendingUploadMode.folder to indicate whether to assume it’s a file or folder.
Return type:dropbox.sharing.PathLinkMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.CreateSharedLinkError

Create a shared link with custom settings. If no settings are given then the default visibility is RequestedVisibility.public (The resolved visibility, though, may depend on other aspects such as team and shared folder settings).

Route attributes:
scope: sharing.write
Parameters:path (str) – The path to be shared by the shared link.
:param Nullable[dropbox.sharing.SharedLinkSettings] settings:
The requested settings for the newly created shared link.
Return type:dropbox.sharing.SharedLinkMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.CreateSharedLinkWithSettingsError
sharing_get_file_metadata(file, actions=None)

Returns shared file metadata.

Route attributes:
scope: sharing.read
Parameters:file (str) – The file to query.
:param Nullable[List[dropbox.sharing.FileAction]] actions: A
list of FileAction`s corresponding to `FilePermission`s that should appear in the response’s ``SharedFileMetadata.permissions` field describing the actions the authenticated user can perform on the file.
Return type:dropbox.sharing.SharedFileMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.GetFileMetadataError
sharing_get_file_metadata_batch(files, actions=None)

Returns shared file metadata.

Route attributes:
scope: sharing.read
Parameters:files (List[str]) – The files to query.
:param Nullable[List[dropbox.sharing.FileAction]] actions: A
list of FileAction`s corresponding to `FilePermission`s that should appear in the response’s ``SharedFileMetadata.permissions` field describing the actions the authenticated user can perform on the file.
Return type:List[dropbox.sharing.GetFileMetadataBatchResult]
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.SharingUserError
sharing_get_folder_metadata(shared_folder_id, actions=None)

Returns shared folder metadata by its folder ID.

Route attributes:
scope: sharing.read
Parameters:shared_folder_id (str) – The ID for the shared folder.
:param Nullable[List[dropbox.sharing.FolderAction]] actions: A
list of FolderAction`s corresponding to `FolderPermission`s that should appear in the response’s ``SharedFolderMetadata.permissions` field describing the actions the authenticated user can perform on the folder.
Return type:dropbox.sharing.SharedFolderMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.SharedFolderAccessError

Download the shared link’s file from a user’s Dropbox.

Route attributes:
scope: sharing.read
Parameters:
  • url (str) – URL of the shared link.
  • path (Nullable[str]) – If the shared link is to a folder, this parameter can be used to retrieve the metadata for a specific file or sub-folder in this folder. A relative path should be used.
  • link_password (Nullable[str]) – If the shared link has a password, this parameter can be used.
Return type:

(dropbox.sharing.SharedLinkMetadata, requests.models.Response)

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.GetSharedLinkFileError

If you do not consume the entire response body, then you must call close on the response object, otherwise you will max out your available connections. We recommend using the contextlib.closing context manager to ensure this.

Download the shared link’s file from a user’s Dropbox.

Route attributes:
scope: sharing.read
Parameters:
  • download_path (str) – Path on local machine to save file.
  • url (str) – URL of the shared link.
  • path (Nullable[str]) – If the shared link is to a folder, this parameter can be used to retrieve the metadata for a specific file or sub-folder in this folder. A relative path should be used.
  • link_password (Nullable[str]) – If the shared link has a password, this parameter can be used.
Return type:

dropbox.sharing.SharedLinkMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.GetSharedLinkFileError

Get the shared link’s metadata.

Route attributes:
scope: sharing.read
Parameters:
  • url (str) – URL of the shared link.
  • path (Nullable[str]) – If the shared link is to a folder, this parameter can be used to retrieve the metadata for a specific file or sub-folder in this folder. A relative path should be used.
  • link_password (Nullable[str]) – If the shared link has a password, this parameter can be used.
Return type:

dropbox.sharing.SharedLinkMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.SharedLinkError

Returns a list of dropbox.sharing.LinkMetadata objects for this user, including collection links. If no path is given, returns a list of all shared links for the current user, including collection links, up to a maximum of 1000 links. If a non-empty path is given, returns a list of all shared links that allow access to the given path. Collection links are never returned in this case.

Route attributes:
scope: sharing.read
Parameters:path (Nullable[str]) – See sharing_get_shared_links() description.
Return type:dropbox.sharing.GetSharedLinksResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.GetSharedLinksError
sharing_list_file_members(file, actions=None, include_inherited=True, limit=100)

Use to obtain the members who have been invited to a file, both inherited and uninherited members.

Route attributes:
scope: sharing.read
Parameters:file (str) – The file for which you want to see members.
:param Nullable[List[dropbox.sharing.MemberAction]] actions:
The actions for which to return permissions on a member.
Parameters:
  • include_inherited (bool) – Whether to include members who only have access from a parent shared folder.
  • limit (int) – Number of members to return max per query. Defaults to 100 if no limit is specified.
Return type:

dropbox.sharing.SharedFileMembers

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.ListFileMembersError
sharing_list_file_members_batch(files, limit=10)

Get members of multiple files at once. The arguments to this route are more limited, and the limit on query result size per file is more strict. To customize the results more, use the individual file endpoint. Inherited users and groups are not included in the result, and permissions are not returned for this endpoint.

Route attributes:
scope: sharing.read
Parameters:
  • files (List[str]) – Files for which to return members.
  • limit (int) – Number of members to return max per query. Defaults to 10 if no limit is specified.
Return type:

List[dropbox.sharing.ListFileMembersBatchResult]

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.SharingUserError
sharing_list_file_members_continue(cursor)

Once a cursor has been retrieved from sharing_list_file_members() or sharing_list_file_members_batch(), use this to paginate through all shared file members.

Route attributes:
scope: sharing.read
Parameters:cursor (str) – The cursor returned by your last call to sharing_list_file_members(), sharing_list_file_members_continue(), or sharing_list_file_members_batch().
Return type:dropbox.sharing.SharedFileMembers
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ListFileMembersContinueError
sharing_list_folder_members(shared_folder_id, actions=None, limit=1000)

Returns shared folder membership by its folder ID.

Route attributes:
scope: sharing.read
Parameters:shared_folder_id (str) – The ID for the shared folder.
Return type:dropbox.sharing.SharedFolderMembers
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.SharedFolderAccessError
sharing_list_folder_members_continue(cursor)

Once a cursor has been retrieved from sharing_list_folder_members(), use this to paginate through all shared folder members.

Route attributes:
scope: sharing.read
Parameters:cursor (str) – The cursor returned by your last call to sharing_list_folder_members() or sharing_list_folder_members_continue().
Return type:dropbox.sharing.SharedFolderMembers
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ListFolderMembersContinueError
sharing_list_folders(limit=1000, actions=None)

Return the list of all shared folders the current user has access to.

Route attributes:
scope: sharing.read
Parameters:limit (int) – The maximum number of results to return per request.
:param Nullable[List[dropbox.sharing.FolderAction]] actions: A
list of FolderAction`s corresponding to `FolderPermission`s that should appear in the response’s ``SharedFolderMetadata.permissions` field describing the actions the authenticated user can perform on the folder.
Return type:dropbox.sharing.ListFoldersResult
sharing_list_folders_continue(cursor)

Once a cursor has been retrieved from sharing_list_folders(), use this to paginate through all shared folders. The cursor must come from a previous call to sharing_list_folders() or sharing_list_folders_continue().

Route attributes:
scope: sharing.read
Parameters:cursor (str) – The cursor returned by the previous API call specified in the endpoint description.
Return type:dropbox.sharing.ListFoldersResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ListFoldersContinueError
sharing_list_mountable_folders(limit=1000, actions=None)

Return the list of all shared folders the current user can mount or unmount.

Route attributes:
scope: sharing.read
Parameters:limit (int) – The maximum number of results to return per request.
:param Nullable[List[dropbox.sharing.FolderAction]] actions: A
list of FolderAction`s corresponding to `FolderPermission`s that should appear in the response’s ``SharedFolderMetadata.permissions` field describing the actions the authenticated user can perform on the folder.
Return type:dropbox.sharing.ListFoldersResult
sharing_list_mountable_folders_continue(cursor)

Once a cursor has been retrieved from sharing_list_mountable_folders(), use this to paginate through all mountable shared folders. The cursor must come from a previous call to sharing_list_mountable_folders() or sharing_list_mountable_folders_continue().

Route attributes:
scope: sharing.read
Parameters:cursor (str) – The cursor returned by the previous API call specified in the endpoint description.
Return type:dropbox.sharing.ListFoldersResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ListFoldersContinueError
sharing_list_received_files(limit=100, actions=None)

Returns a list of all files shared with current user. Does not include files the user has received via shared folders, and does not include unclaimed invitations.

Route attributes:
scope: sharing.read
Parameters:limit (int) – Number of files to return max per query. Defaults to 100 if no limit is specified.
:param Nullable[List[dropbox.sharing.FileAction]] actions: A
list of FileAction`s corresponding to `FilePermission`s that should appear in the response’s ``SharedFileMetadata.permissions` field describing the actions the authenticated user can perform on the file.
Return type:dropbox.sharing.ListFilesResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.SharingUserError
sharing_list_received_files_continue(cursor)

Get more results with a cursor from sharing_list_received_files().

Route attributes:
scope: sharing.read
Parameters:cursor (str) – Cursor in ListFilesResult.cursor.
Return type:dropbox.sharing.ListFilesResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ListFilesContinueError

List shared links of this user. If no path is given, returns a list of all shared links for the current user. For members of business teams using team space and member folders, returns all shared links in the team member’s home folder unless the team space ID is specified in the request header. For more information, refer to the Namespace Guide. If a non-empty path is given, returns a list of all shared links that allow access to the given path - direct links to the given path and links to parent folders of the given path. Links to parent folders can be suppressed by setting direct_only to true.

Route attributes:
scope: sharing.read
Parameters:
Return type:

dropbox.sharing.ListSharedLinksResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.ListSharedLinksError

Modify the shared link’s settings. If the requested visibility conflict with the shared links policy of the team or the shared folder (in case the linked file is part of a shared folder) then the LinkPermissions.resolved_visibility of the returned dropbox.sharing.SharedLinkMetadata will reflect the actual visibility of the shared link and the LinkPermissions.requested_visibility will reflect the requested visibility.

Route attributes:
scope: sharing.write
Parameters:
  • url (str) – URL of the shared link to change its settings.
  • settings (dropbox.sharing.SharedLinkSettings) – Set of settings for the shared link.
  • remove_expiration (bool) – If set to true, removes the expiration of the shared link.
Return type:

dropbox.sharing.SharedLinkMetadata

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.ModifySharedLinkSettingsError
sharing_mount_folder(shared_folder_id)

The current user mounts the designated folder. Mount a shared folder for a user after they have been added as a member. Once mounted, the shared folder will appear in their Dropbox.

Route attributes:
scope: sharing.write
Parameters:shared_folder_id (str) – The ID of the shared folder to mount.
Return type:dropbox.sharing.SharedFolderMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.MountFolderError
sharing_relinquish_file_membership(file)

The current user relinquishes their membership in the designated file. Note that the current user may still have inherited access to this file through the parent folder.

Route attributes:
scope: sharing.write
Parameters:file (str) – The path or id for the file.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.RelinquishFileMembershipError
sharing_relinquish_folder_membership(shared_folder_id, leave_a_copy=False)

The current user relinquishes their membership in the designated shared folder and will no longer have access to the folder. A folder owner cannot relinquish membership in their own folder. This will run synchronously if leave_a_copy is false, and asynchronously if leave_a_copy is true.

Route attributes:
scope: sharing.write
Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • leave_a_copy (bool) – Keep a copy of the folder’s contents upon relinquishing membership. This must be set to false when the folder is within a team folder or another shared folder.
Return type:

dropbox.sharing.LaunchEmptyResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.RelinquishFolderMembershipError
sharing_remove_file_member(file, member)

Identical to remove_file_member_2 but with less information returned.

Route attributes:
scope: sharing.write
Parameters:
  • file (str) – File from which to remove members.
  • member (dropbox.sharing.MemberSelector) – Member to remove from this file. Note that even if an email is specified, it may result in the removal of a user (not an invitee) if the user’s main account corresponds to that email address.
Return type:

dropbox.sharing.FileMemberActionIndividualResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.RemoveFileMemberError
sharing_remove_file_member_2(file, member)

Removes a specified member from the file.

Route attributes:
scope: sharing.write
Parameters:
  • file (str) – File from which to remove members.
  • member (dropbox.sharing.MemberSelector) – Member to remove from this file. Note that even if an email is specified, it may result in the removal of a user (not an invitee) if the user’s main account corresponds to that email address.
Return type:

dropbox.sharing.FileMemberRemoveActionResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.RemoveFileMemberError
sharing_remove_folder_member(shared_folder_id, member, leave_a_copy)

Allows an owner or editor (if the ACL update policy allows) of a shared folder to remove another member.

Route attributes:
scope: sharing.write
Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • member (dropbox.sharing.MemberSelector) – The member to remove from the folder.
  • leave_a_copy (bool) – If true, the removed user will keep their copy of the folder after it’s unshared, assuming it was mounted. Otherwise, it will be removed from their Dropbox. This must be set to false when removing a group, or when the folder is within a team folder or another shared folder.
Return type:

dropbox.sharing.LaunchResultBase

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.RemoveFolderMemberError

Revoke a shared link. Note that even after revoking a shared link to a file, the file may be accessible if there are shared links leading to any of the file parent folders. To list all shared links that enable access to a specific file, you can use the sharing_list_shared_links() with the file as the ListSharedLinksArg.path argument.

Route attributes:
scope: sharing.write
Parameters:url (str) – URL of the shared link.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.RevokeSharedLinkError
sharing_set_access_inheritance(shared_folder_id, access_inheritance=AccessInheritance(u'inherit', None))

Change the inheritance policy of an existing Shared Folder. Only permitted for shared folders in a shared team root. If a ShareFolderLaunch.async_job_id is returned, you’ll need to call sharing_check_share_job_status() until the action completes to get the metadata for the folder.

Route attributes:
scope: sharing.write
Parameters:
  • access_inheritance (dropbox.sharing.AccessInheritance) – The access inheritance settings for the folder.
  • shared_folder_id (str) – The ID for the shared folder.
Return type:

dropbox.sharing.ShareFolderLaunch

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.SetAccessInheritanceError
sharing_share_folder(path, acl_update_policy=None, force_async=False, member_policy=None, shared_link_policy=None, viewer_info_policy=None, access_inheritance=AccessInheritance(u'inherit', None), actions=None, link_settings=None)

Share a folder with collaborators. Most sharing will be completed synchronously. Large folders will be completed asynchronously. To make testing the async case repeatable, set ShareFolderArg.force_async. If a ShareFolderLaunch.async_job_id is returned, you’ll need to call sharing_check_share_job_status() until the action completes to get the metadata for the folder.

Route attributes:
scope: sharing.write
:param Nullable[List[dropbox.sharing.FolderAction]] actions: A
list of FolderAction`s corresponding to `FolderPermission`s that should appear in the response’s ``SharedFolderMetadata.permissions` field describing the actions the authenticated user can perform on the folder.
:param Nullable[dropbox.sharing.LinkSettings] link_settings:
Settings on the link for this folder.
Return type:dropbox.sharing.ShareFolderLaunch
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.ShareFolderError
sharing_transfer_folder(shared_folder_id, to_dropbox_id)

Transfer ownership of a shared folder to a member of the shared folder. User must have AccessLevel.owner access to the shared folder to perform a transfer.

Route attributes:
scope: sharing.write
Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • to_dropbox_id (str) – A account or team member ID to transfer ownership to.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.TransferFolderError
sharing_unmount_folder(shared_folder_id)

The current user unmounts the designated folder. They can re-mount the folder at a later time using sharing_mount_folder().

Route attributes:
scope: sharing.write
Parameters:shared_folder_id (str) – The ID for the shared folder.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.UnmountFolderError
sharing_unshare_file(file)

Remove all members from this file. Does not remove inherited members.

Route attributes:
scope: sharing.write
Parameters:file (str) – The file to unshare.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.UnshareFileError
sharing_unshare_folder(shared_folder_id, leave_a_copy=False)

Allows a shared folder owner to unshare the folder. You’ll need to call sharing_check_job_status() to determine if the action has completed successfully.

Route attributes:
scope: sharing.write
Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • leave_a_copy (bool) – If true, members of this shared folder will get a copy of this folder after it’s unshared. Otherwise, it will be removed from their Dropbox. The current user, who is an owner, will always retain their copy.
Return type:

dropbox.sharing.LaunchEmptyResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.UnshareFolderError
sharing_update_file_member(file, member, access_level)

Changes a member’s access on a shared file.

Route attributes:
scope: sharing.write
Parameters:
Return type:

dropbox.sharing.MemberAccessLevelResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.FileMemberActionError
sharing_update_folder_member(shared_folder_id, member, access_level)

Allows an owner or editor of a shared folder to update another member’s permissions.

Route attributes:
scope: sharing.write
Parameters:
  • shared_folder_id (str) – The ID for the shared folder.
  • member (dropbox.sharing.MemberSelector) – The member of the shared folder to update. Only the MemberSelector.dropbox_id may be set at this time.
  • access_level (dropbox.sharing.AccessLevel) – The new access level for member. AccessLevel.owner is disallowed.
Return type:

dropbox.sharing.MemberAccessLevelResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.sharing.UpdateFolderMemberError
sharing_update_folder_policy(shared_folder_id, member_policy=None, acl_update_policy=None, viewer_info_policy=None, shared_link_policy=None, link_settings=None, actions=None)

Update the sharing policies for a shared folder. User must have AccessLevel.owner access to the shared folder to update its policies.

Route attributes:
scope: sharing.write
Parameters:shared_folder_id (str) – The ID for the shared folder.
:param Nullable[dropbox.sharing.MemberPolicy] member_policy:
Who can be a member of this shared folder. Only applicable if the current user is on a team.
:param Nullable[dropbox.sharing.AclUpdatePolicy]
acl_update_policy: Who can add and remove members of this shared folder.
:param Nullable[dropbox.sharing.ViewerInfoPolicy]
viewer_info_policy: Who can enable/disable viewer info for this shared folder.
:param Nullable[dropbox.sharing.SharedLinkPolicy]
shared_link_policy: The policy to apply to shared links created for content inside this shared folder. The current user must be on a team to set this policy to SharedLinkPolicy.members.
:param Nullable[dropbox.sharing.LinkSettings] link_settings:
Settings on the link for this folder.
:param Nullable[List[dropbox.sharing.FolderAction]] actions: A
list of FolderAction`s corresponding to `FolderPermission`s that should appear in the response’s ``SharedFolderMetadata.permissions` field describing the actions the authenticated user can perform on the folder.
Return type:dropbox.sharing.SharedFolderMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.sharing.UpdateFolderPolicyError
users_features_get_values(features)

Get a list of feature values that may be configured for the current account.

Route attributes:
scope: account_info.read
:param List[dropbox.users.UserFeature] features: A list of
features in dropbox.users.UserFeature. If the list is empty, this route will return dropbox.users.UserFeaturesGetValuesBatchError.
Return type:dropbox.users.UserFeaturesGetValuesBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.users.UserFeaturesGetValuesBatchError
users_get_account(account_id)

Get information about a user’s account.

Route attributes:
scope: sharing.read
Parameters:account_id (str) – A user’s account identifier.
Return type:dropbox.users.BasicAccount
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.users.GetAccountError
users_get_account_batch(account_ids)

Get information about multiple user accounts. At most 300 accounts may be queried per request.

Route attributes:
scope: sharing.read
Parameters:account_ids (List[str]) – List of user account identifiers. Should not contain any duplicate account IDs.
Return type:List[dropbox.users.BasicAccount]
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.users.GetAccountBatchError
users_get_current_account()

Get information about the current user’s account.

Route attributes:
scope: account_info.read
Return type:dropbox.users.FullAccount
users_get_space_usage()

Get the space usage information for the current user’s account.

Route attributes:
scope: account_info.read
Return type:dropbox.users.SpaceUsage
with_path_root(path_root)

Creates a clone of the Dropbox instance with the Dropbox-API-Path-Root header as the appropriate serialized instance of PathRoot.

For more information, see https://www.dropbox.com/developers/reference/namespace-guide#pathrootmodes

Parameters:path_root (PathRoot) – instance of PathRoot to serialize into the headers field
Returns:A :class: Dropbox
Return type:Dropbox
class dropbox.dropbox_client.DropboxTeam(oauth2_access_token=None, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=None, ca_certs=None)

Bases: dropbox.dropbox_client._DropboxTransport, dropbox.base_team.DropboxTeamBase

Use this class to make requests to the Dropbox API using a team’s access token. Methods of this class are meant to act on the team, but there is also an as_user() method for assuming a team member’s identity.

__init__(oauth2_access_token=None, max_retries_on_error=4, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=100, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=None, ca_certs=None)
Parameters:
  • oauth2_access_token (str) – OAuth2 access token for making client requests.
  • max_retries_on_error (int) – On 5xx errors, the number of times to retry.
  • max_retries_on_rate_limit (Optional[int]) – On 429 errors, the number of times to retry. If None, always retries.
  • user_agent (str) – The user agent to use when making requests. This helps us identify requests coming from your application. We recommend you use the format “AppName/Version”. If set, we append “/OfficialDropboxPythonSDKv2/__version__” to the user_agent,
  • session (requests.sessions.Session) – If not provided, a new session (connection pool) is created. To share a session across multiple clients, use create_session().
  • headers (dict) – Additional headers to add to requests.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, client will wait forever. Defaults to 100 seconds.
  • oauth2_refresh_token (str) – OAuth2 refresh token for refreshing access token
  • oauth2_access_token_expiration (datetime) – Expiration for oauth2_access_token
  • app_key (str) – application key of requesting application; used for token refresh
  • app_secret (str) – application secret of requesting application; used for token refresh Not required if PKCE was used to authorize the token
  • scope (list) – list of scopes to request on refresh. If left blank, refresh will request all available scopes for application
  • ca_certs (str) – path to CA certificate. If left blank, default certificate location will be used
as_admin(team_member_id)

Allows a team credential to assume the identity of an administrator on the team and perform operations on any team-owned content.

Parameters:team_member_id (str) – team member id of administrator to perform actions with
Returns:A Dropbox object that can be used to query on behalf of this admin of the team.
Return type:Dropbox
as_user(team_member_id)

Allows a team credential to assume the identity of a member of the team.

Parameters:team_member_id (str) – team member id of team member to perform actions with
Returns:A Dropbox object that can be used to query on behalf of this member of the team.
Return type:Dropbox
check_and_refresh_access_token()

Checks if access token needs to be refreshed and refreshes if possible :return:

clone(oauth2_access_token=None, max_retries_on_error=None, max_retries_on_rate_limit=None, user_agent=None, session=None, headers=None, timeout=None, oauth2_refresh_token=None, oauth2_access_token_expiration=None, app_key=None, app_secret=None, scope=None)

Creates a new copy of the Dropbox client with the same defaults unless modified by arguments to clone()

See constructor for original parameter descriptions.

Returns:New instance of Dropbox client
Return type:Dropbox
close()

Cleans up all resources like the request session/network connection.

file_properties_templates_add_for_team(name, description, fields)

Add a template associated with a team. See file_properties_properties_add() to add properties to a file or folder. Note: this endpoint will create team-owned templates.

Route attributes:
scope: files.team_metadata.write
Return type:dropbox.file_properties.AddTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.ModifyTemplateError
file_properties_templates_get_for_team(template_id)

Get the schema for a specified template.

Route attributes:
scope: files.team_metadata.write
Parameters:template_id (str) – An identifier for template added by route See file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
Return type:dropbox.file_properties.GetTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_list_for_team()

Get the template identifiers for a team. To get the schema of each template use file_properties_templates_get_for_team().

Route attributes:
scope: files.team_metadata.write
Return type:dropbox.file_properties.ListTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_remove_for_team(template_id)

Permanently removes the specified template created from file_properties_templates_add_for_user(). All properties associated with the template will also be removed. This action cannot be undone.

Route attributes:
scope: files.team_metadata.write
Parameters:template_id (str) – An identifier for a template created by file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.TemplateError
file_properties_templates_update_for_team(template_id, name=None, description=None, add_fields=None)

Update a template associated with a team. This route can update the template name, the template description and add optional properties to templates.

Route attributes:
scope: files.team_metadata.write
Parameters:
  • template_id (str) – An identifier for template added by See file_properties_templates_add_for_user() or file_properties_templates_add_for_team().
  • name (Nullable[str]) – A display name for the template. template names can be up to 256 bytes.
  • description (Nullable[str]) – Description for the new template. Template descriptions can be up to 1024 bytes.
:param
Nullable[List[dropbox.file_properties.PropertyFieldTemplate]] add_fields: Property field templates to be added to the group template. There can be up to 32 properties in a single template.
Return type:dropbox.file_properties.UpdateTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.file_properties.ModifyTemplateError
raise_dropbox_error_for_resp(res)

Checks for errors from a res and handles appropiately.

Parameters:res – Response of an api request.
refresh_access_token(host='api.dropboxapi.com', scope=None)

Refreshes an access token via refresh token if available

Parameters:
  • host – host to hit token endpoint with
  • scope – list of permission scopes for access token
Returns:

request(route, namespace, request_arg, request_binary, timeout=None)

Makes a request to the Dropbox API and in the process validates that the route argument and result are the expected data types. The request_arg is converted to JSON based on the arg_data_type. Likewise, the response is deserialized from JSON and converted to an object based on the {result,error}_data_type.

Parameters:
  • host – The Dropbox API host to connect to.
  • route (stone.backends.python_rsrc.stone_base.Route) – The route to make the request to.
  • request_arg – Argument for the route that conforms to the validator specified by route.arg_type.
  • request_binary – String or file pointer representing the binary payload. Use None if there is no binary payload.
  • timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, will use default timeout set on Dropbox object. Defaults to None.
Returns:

The route’s result.

request_json_object(host, route_name, route_style, request_arg, auth_type, request_binary, timeout=None)

Makes a request to the Dropbox API, taking a JSON-serializable Python object as an argument, and returning one as a response.

Parameters:
  • host – The Dropbox API host to connect to.
  • route_name – The name of the route to invoke.
  • route_style – The style of the route.
  • request_arg (str) – A JSON-serializable Python object representing the argument for the route.

:param auth_type str :param Optional[bytes] request_binary: Bytes representing the binary

payload. Use None if there is no binary payload.
Parameters:timeout (Optional[float]) – Maximum duration in seconds that client will wait for any single packet from the server. After the timeout the client will give up on connection. If None, will use default timeout set on Dropbox object. Defaults to None.
Returns:The route’s result as a JSON-serializable Python object.
request_json_string(host, func_name, route_style, request_json_arg, auth_type, request_binary, timeout=None)

See request_json_string_with_retry() for description of parameters.

request_json_string_with_retry(host, route_name, route_style, request_json_arg, auth_type, request_binary, timeout=None)

See request_json_object() for description of parameters.

Parameters:request_json_arg – A string representing the serialized JSON argument to the route.
team_devices_list_member_devices(team_member_id, include_web_sessions=True, include_desktop_clients=True, include_mobile_clients=True)

List all device sessions of a team’s member.

Route attributes:
scope: sessions.list
Parameters:
  • team_member_id (str) – The team’s member id.
  • include_web_sessions (bool) – Whether to list web sessions of the team’s member.
  • include_desktop_clients (bool) – Whether to list linked desktop devices of the team’s member.
  • include_mobile_clients (bool) – Whether to list linked mobile devices of the team’s member.
Return type:

dropbox.team.ListMemberDevicesResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.ListMemberDevicesError
team_devices_list_members_devices(cursor=None, include_web_sessions=True, include_desktop_clients=True, include_mobile_clients=True)

List all device sessions of a team. Permission : Team member file access.

Route attributes:
scope: sessions.list
Parameters:
  • cursor (Nullable[str]) – At the first call to the team_devices_list_members_devices() the cursor shouldn’t be passed. Then, if the result of the call includes a cursor, the following requests should include the received cursors in order to receive the next sub list of team devices.
  • include_web_sessions (bool) – Whether to list web sessions of the team members.
  • include_desktop_clients (bool) – Whether to list desktop clients of the team members.
  • include_mobile_clients (bool) – Whether to list mobile clients of the team members.
Return type:

dropbox.team.ListMembersDevicesResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.ListMembersDevicesError
team_devices_list_team_devices(cursor=None, include_web_sessions=True, include_desktop_clients=True, include_mobile_clients=True)

List all device sessions of a team. Permission : Team member file access.

Route attributes:
scope: sessions.list
Parameters:
  • cursor (Nullable[str]) – At the first call to the team_devices_list_team_devices() the cursor shouldn’t be passed. Then, if the result of the call includes a cursor, the following requests should include the received cursors in order to receive the next sub list of team devices.
  • include_web_sessions (bool) – Whether to list web sessions of the team members.
  • include_desktop_clients (bool) – Whether to list desktop clients of the team members.
  • include_mobile_clients (bool) – Whether to list mobile clients of the team members.
Return type:

dropbox.team.ListTeamDevicesResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.ListTeamDevicesError
team_devices_revoke_device_session(arg)

Revoke a device session of a team’s member.

Route attributes:
scope: sessions.modify
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.RevokeDeviceSessionError
team_devices_revoke_device_session_batch(revoke_devices)

Revoke a list of device sessions of team members.

Route attributes:
scope: sessions.modify
Return type:dropbox.team.RevokeDeviceSessionBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.RevokeDeviceSessionBatchError
team_features_get_values(features)

Get the values for one or more featues. This route allows you to check your account’s capability for what feature you can access or what value you have for certain features. Permission : Team information.

Route attributes:
scope: team_info.read
:param List[dropbox.team.Feature] features: A list of features
in dropbox.team.Feature. If the list is empty, this route will return dropbox.team.FeaturesGetValuesBatchError.
Return type:dropbox.team.FeaturesGetValuesBatchResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.FeaturesGetValuesBatchError
team_get_info()

Retrieves information about a team.

Route attributes:
scope: team_info.read
Return type:dropbox.team.TeamGetInfoResult
team_groups_create(group_name, add_creator_as_owner=False, group_external_id=None, group_management_type=None)

Creates a new, empty group, with a requested name. Permission : Team member management.

Route attributes:
scope: groups.write
Parameters:
  • group_name (str) – Group name.
  • add_creator_as_owner (bool) – Automatically add the creator of the group.
  • group_external_id (Nullable[str]) – The creator of a team can associate an arbitrary external ID to the group.
:param Nullable[dropbox.team.GroupManagementType]
group_management_type: Whether the team can be managed by selected users, or only by team admins.
Return type:dropbox.team.GroupFullInfo
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupCreateError
team_groups_delete(arg)

Deletes a group. The group is deleted immediately. However the revoking of group-owned resources may take additional time. Use the team_groups_job_status_get() to determine whether this process has completed. Permission : Team member management.

Route attributes:
scope: groups.write
Parameters:arg (dropbox.team.GroupSelector) – Argument for selecting a single group, either by group_id or by external group ID.
Return type:dropbox.team.LaunchEmptyResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupDeleteError
team_groups_get_info(arg)

Retrieves information about one or more groups. Note that the optional field GroupFullInfo.members is not returned for system-managed groups. Permission : Team Information.

Route attributes:
scope: groups.read
Parameters:arg (dropbox.team.GroupsSelector) – Argument for selecting a list of groups, either by group_ids, or external group IDs.
Return type:List[dropbox.team.GroupsGetInfoItem]
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupsGetInfoError
team_groups_job_status_get(async_job_id)

Once an async_job_id is returned from team_groups_delete(), team_groups_members_add() , or team_groups_members_remove() use this method to poll the status of granting/revoking group members’ access to group-owned resources. Permission : Team member management.

Route attributes:
scope: groups.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.PollEmptyResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupsPollError
team_groups_list(limit=1000)

Lists groups on a team. Permission : Team Information.

Route attributes:
scope: groups.read
Parameters:limit (int) – Number of results to return per call.
Return type:dropbox.team.GroupsListResult
team_groups_list_continue(cursor)

Once a cursor has been retrieved from team_groups_list(), use this to paginate through all groups. Permission : Team Information.

Route attributes:
scope: groups.read
Parameters:cursor (str) – Indicates from what point to get the next set of groups.
Return type:dropbox.team.GroupsListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupsListContinueError
team_groups_members_add(group, members, return_members=True)

Adds members to a group. The members are added immediately. However the granting of group-owned resources may take additional time. Use the team_groups_job_status_get() to determine whether this process has completed. Permission : Team member management.

Route attributes:
scope: groups.write
Parameters:group (dropbox.team.GroupSelector) – Group to which users will be added.
:param List[dropbox.team.MemberAccess] members: List of users
to be added to the group.
Return type:dropbox.team.GroupMembersChangeResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupMembersAddError
team_groups_members_list(group, limit=1000)

Lists members of a group. Permission : Team Information.

Route attributes:
scope: groups.read
Parameters:
  • group (dropbox.team.GroupSelector) – The group whose members are to be listed.
  • limit (int) – Number of results to return per call.
Return type:

dropbox.team.GroupsMembersListResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.GroupSelectorError
team_groups_members_list_continue(cursor)

Once a cursor has been retrieved from team_groups_members_list(), use this to paginate through all members of the group. Permission : Team information.

Route attributes:
scope: groups.read
Parameters:cursor (str) – Indicates from what point to get the next set of groups.
Return type:dropbox.team.GroupsMembersListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupsMembersListContinueError
team_groups_members_remove(group, users, return_members=True)

Removes members from a group. The members are removed immediately. However the revoking of group-owned resources may take additional time. Use the team_groups_job_status_get() to determine whether this process has completed. This method permits removing the only owner of a group, even in cases where this is not possible via the web client. Permission : Team member management.

Route attributes:
scope: groups.write
Parameters:group (dropbox.team.GroupSelector) – Group from which users will be removed.
:param List[dropbox.team.UserSelectorArg] users: List of users
to be removed from the group.
Return type:dropbox.team.GroupMembersChangeResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupMembersRemoveError
team_groups_members_set_access_type(group, user, access_type, return_members=True)

Sets a member’s access type in a group. Permission : Team member management.

Route attributes:
scope: groups.write
Parameters:
  • access_type (dropbox.team.GroupAccessType) – New group access type the user will have.
  • return_members (bool) – Whether to return the list of members in the group. Note that the default value will cause all the group members to be returned in the response. This may take a long time for large groups.
Return type:

List[dropbox.team.GroupsGetInfoItem]

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.GroupMemberSetAccessTypeError
team_groups_update(group, return_members=True, new_group_name=None, new_group_external_id=None, new_group_management_type=None)

Updates a group’s name and/or external ID. Permission : Team member management.

Route attributes:
scope: groups.write
Parameters:
  • group (dropbox.team.GroupSelector) – Specify a group.
  • new_group_name (Nullable[str]) – Optional argument. Set group name to this if provided.
  • new_group_external_id (Nullable[str]) – Optional argument. New group external ID. If the argument is None, the group’s external_id won’t be updated. If the argument is empty string, the group’s external id will be cleared.
:param Nullable[dropbox.team.GroupManagementType]
new_group_management_type: Set new group management type, if provided.
Return type:dropbox.team.GroupFullInfo
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.GroupUpdateError

Creates new legal hold policy. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.

Route attributes:
scope: team_data.governance.write
Parameters:
  • name (str) – Policy name.
  • description (Nullable[str]) – A description of the legal hold policy.
  • members (List[str]) – List of team member IDs added to the hold.
  • start_date (Nullable[datetime]) – start date of the legal hold policy.
  • end_date (Nullable[datetime]) – end date of the legal hold policy.
Return type:

dropbox.team.LegalHoldPolicy

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.LegalHoldsPolicyCreateError

Gets a legal hold by Id. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.

Route attributes:
scope: team_data.governance.write
Parameters:id (str) – The legal hold Id.
Return type:dropbox.team.LegalHoldPolicy
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.LegalHoldsGetPolicyError

List the file metadata that’s under the hold. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.

Route attributes:
scope: team_data.governance.write
Parameters:id (str) – The legal hold Id.
Return type:dropbox.team.LegalHoldsListHeldRevisionResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.LegalHoldsListHeldRevisionsError

Continue listing the file metadata that’s under the hold. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.

Route attributes:
scope: team_data.governance.write
Parameters:
  • id (str) – The legal hold Id.
  • cursor (Nullable[str]) – The cursor idicates where to continue reading file metadata entries for the next API call. When there are no more entries, the cursor will return none.
Return type:

dropbox.team.LegalHoldsListHeldRevisionResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.LegalHoldsListHeldRevisionsError

Lists legal holds on a team. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.

Route attributes:
scope: team_data.governance.write
Parameters:include_released (bool) – Whether to return holds that were released.
Return type:dropbox.team.LegalHoldsListPoliciesResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.LegalHoldsListPoliciesError

Releases a legal hold by Id. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.

Route attributes:
scope: team_data.governance.write
Parameters:id (str) – The legal hold Id.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.LegalHoldsPolicyReleaseError

Updates a legal hold. Note: Legal Holds is a paid add-on. Not all teams have the feature. Permission : Team member file access.

Route attributes:
scope: team_data.governance.write
Parameters:
  • id (str) – The legal hold Id.
  • name (Nullable[str]) – Policy new name.
  • description (Nullable[str]) – Policy new description.
  • members (Nullable[List[str]]) – List of team member IDs to apply the policy on.
Return type:

dropbox.team.LegalHoldPolicy

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.LegalHoldsPolicyUpdateError
team_linked_apps_list_member_linked_apps(team_member_id)

List all linked applications of the team member. Note, this endpoint does not list any team-linked applications.

Route attributes:
scope: sessions.list
Parameters:team_member_id (str) – The team member id.
Return type:dropbox.team.ListMemberAppsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ListMemberAppsError
team_linked_apps_list_members_linked_apps(cursor=None)

List all applications linked to the team members’ accounts. Note, this endpoint does not list any team-linked applications.

Route attributes:
scope: sessions.list
Parameters:cursor (Nullable[str]) – At the first call to the team_linked_apps_list_members_linked_apps() the cursor shouldn’t be passed. Then, if the result of the call includes a cursor, the following requests should include the received cursors in order to receive the next sub list of the team applications.
Return type:dropbox.team.ListMembersAppsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ListMembersAppsError
team_linked_apps_list_team_linked_apps(cursor=None)

List all applications linked to the team members’ accounts. Note, this endpoint doesn’t list any team-linked applications.

Route attributes:
scope: sessions.list
Parameters:cursor (Nullable[str]) – At the first call to the team_linked_apps_list_team_linked_apps() the cursor shouldn’t be passed. Then, if the result of the call includes a cursor, the following requests should include the received cursors in order to receive the next sub list of the team applications.
Return type:dropbox.team.ListTeamAppsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ListTeamAppsError
team_linked_apps_revoke_linked_app(app_id, team_member_id, keep_app_folder=True)

Revoke a linked application of the team member.

Route attributes:
scope: sessions.modify
Parameters:
  • app_id (str) – The application’s unique id.
  • team_member_id (str) – The unique id of the member owning the device.
  • keep_app_folder (bool) – This flag is not longer supported, the application dedicated folder (in case the application uses one) will be kept.
Return type:

None

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.RevokeLinkedAppError
team_linked_apps_revoke_linked_app_batch(revoke_linked_app)

Revoke a list of linked applications of the team members.

Route attributes:
scope: sessions.modify

List[dropbox.team.RevokeLinkedApiAppArg] :rtype: dropbox.team.RevokeLinkedAppBatchResult :raises: exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.RevokeLinkedAppBatchError
team_log_get_events(limit=1000, account_id=None, time=None, category=None, event_type=None)

Retrieves team events. If the result’s GetTeamEventsResult.has_more field is True, call team_log_get_events_continue() with the returned cursor to retrieve more entries. If end_time is not specified in your request, you may use the returned cursor to poll team_log_get_events_continue() for new events. Many attributes note ‘may be missing due to historical data gap’. Note that the file_operations category and & analogous paper events are not available on all Dropbox Business plans. Use features/get_values to check for this feature. Permission : Team Auditing.

Route attributes:
scope: events.read
Parameters:
  • limit (int) – The maximal number of results to return per call. Note that some calls may not return limit number of events, and may even return no events, even with has_more set to true. In this case, callers should fetch again using team_log_get_events_continue().
  • account_id (Nullable[str]) – Filter the events by account ID. Return only events with this account_id as either Actor, Context, or Participants.
:param Nullable[dropbox.team_log.TimeRange] time: Filter by
time range.
:param Nullable[dropbox.team_log.EventCategory] category:
Filter the returned events to a single category. Note that category shouldn’t be provided together with event_type.
:param Nullable[dropbox.team_log.EventTypeArg] event_type:
Filter the returned events to a single event type. Note that event_type shouldn’t be provided together with category.
Return type:dropbox.team_log.GetTeamEventsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team_log.GetTeamEventsError
team_log_get_events_continue(cursor)

Once a cursor has been retrieved from team_log_get_events(), use this to paginate through all events. Permission : Team Auditing.

Route attributes:
scope: events.read
Parameters:cursor (str) – Indicates from what point to get the next set of events.
Return type:dropbox.team_log.GetTeamEventsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team_log.GetTeamEventsContinueError
team_member_space_limits_excluded_users_add(users=None)

Add users to member space limits excluded users list.

Route attributes:
scope: members.write
:param Nullable[List[dropbox.team.UserSelectorArg]] users: List
of users to be added/removed.
Return type:dropbox.team.ExcludedUsersUpdateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ExcludedUsersUpdateError
team_member_space_limits_excluded_users_list(limit=1000)

List member space limits excluded users.

Route attributes:
scope: members.read
Parameters:limit (int) – Number of results to return per call.
Return type:dropbox.team.ExcludedUsersListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ExcludedUsersListError
team_member_space_limits_excluded_users_list_continue(cursor)

Continue listing member space limits excluded users.

Route attributes:
scope: members.read
Parameters:cursor (str) – Indicates from what point to get the next set of users.
Return type:dropbox.team.ExcludedUsersListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ExcludedUsersListContinueError
team_member_space_limits_excluded_users_remove(users=None)

Remove users from member space limits excluded users list.

Route attributes:
scope: members.write
:param Nullable[List[dropbox.team.UserSelectorArg]] users: List
of users to be added/removed.
Return type:dropbox.team.ExcludedUsersUpdateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ExcludedUsersUpdateError
team_member_space_limits_get_custom_quota(users)

Get users custom quota. Returns none as the custom quota if none was set. A maximum of 1000 members can be specified in a single call.

Route attributes:
scope: members.read

:param List[dropbox.team.UserSelectorArg] users: List of users. :rtype: List[dropbox.team.CustomQuotaResult] :raises: exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.CustomQuotaError
team_member_space_limits_remove_custom_quota(users)

Remove users custom quota. A maximum of 1000 members can be specified in a single call.

Route attributes:
scope: members.write

:param List[dropbox.team.UserSelectorArg] users: List of users. :rtype: List[dropbox.team.RemoveCustomQuotaResult] :raises: exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.CustomQuotaError
team_member_space_limits_set_custom_quota(users_and_quotas)

Set users custom quota. Custom quota has to be at least 15GB. A maximum of 1000 members can be specified in a single call.

Route attributes:
scope: members.read
:param List[dropbox.team.UserCustomQuotaArg] users_and_quotas:
List of users and their custom quotas.
Return type:List[dropbox.team.CustomQuotaResult]
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.SetCustomQuotaError
team_members_add(new_members, force_async=False)

Adds members to a team. Permission : Team member management A maximum of 20 members can be specified in a single call. If no Dropbox account exists with the email address specified, a new Dropbox account will be created with the given email address, and that account will be invited to the team. If a personal Dropbox account exists with the email address specified in the call, this call will create a placeholder Dropbox account for the user on the team and send an email inviting the user to migrate their existing personal account onto the team. Team member management apps are required to set an initial given_name and surname for a user to use in the team invitation and for ‘Perform as team member’ actions taken on the user before they become ‘active’.

Route attributes:
scope: members.write
:param List[dropbox.team.MemberAddArg] new_members: Details of
new members to be added to the team.
Return type:dropbox.team.MembersAddLaunch
team_members_add_job_status_get(async_job_id)

Once an async_job_id is returned from team_members_add() , use this to poll the status of the asynchronous request. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.MembersAddJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.PollError
team_members_add_job_status_get_v2(async_job_id)

Once an async_job_id is returned from team_members_add_v2() , use this to poll the status of the asynchronous request. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.MembersAddJobStatusV2Result
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.PollError
team_members_add_v2(new_members, force_async=False)

Adds members to a team. Permission : Team member management A maximum of 20 members can be specified in a single call. If no Dropbox account exists with the email address specified, a new Dropbox account will be created with the given email address, and that account will be invited to the team. If a personal Dropbox account exists with the email address specified in the call, this call will create a placeholder Dropbox account for the user on the team and send an email inviting the user to migrate their existing personal account onto the team. Team member management apps are required to set an initial given_name and surname for a user to use in the team invitation and for ‘Perform as team member’ actions taken on the user before they become ‘active’.

Route attributes:
scope: members.write
:param List[dropbox.team.MemberAddV2Arg] new_members: Details
of new members to be added to the team.
Return type:dropbox.team.MembersAddLaunchV2Result
team_members_delete_profile_photo(user)

Deletes a team member’s profile photo. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:user (dropbox.team.UserSelectorArg) – Identity of the user whose profile photo will be deleted.
Return type:dropbox.team.TeamMemberInfo
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersDeleteProfilePhotoError
team_members_delete_profile_photo_v2(user)

Deletes a team member’s profile photo. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:user (dropbox.team.UserSelectorArg) – Identity of the user whose profile photo will be deleted.
Return type:dropbox.team.TeamMemberInfoV2Result
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersDeleteProfilePhotoError
team_members_get_available_team_member_roles()

Get available TeamMemberRoles for the connected team. To be used with team_members_set_admin_permissions_v2(). Permission : Team member management.

Route attributes:
scope: members.read
Return type:dropbox.team.MembersGetAvailableTeamMemberRolesResult
team_members_get_info(members)

Returns information about multiple team members. Permission : Team information This endpoint will return MembersGetInfoItem.id_not_found, for IDs (or emails) that cannot be matched to a valid team member.

Route attributes:
scope: members.read
:param List[dropbox.team.UserSelectorArg] members: List of team
members.
Return type:List[dropbox.team.MembersGetInfoItem]
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersGetInfoError
team_members_get_info_v2(members)

Returns information about multiple team members. Permission : Team information This endpoint will return MembersGetInfoItem.id_not_found, for IDs (or emails) that cannot be matched to a valid team member.

Route attributes:
scope: members.read
:param List[dropbox.team.UserSelectorArg] members: List of team
members.
Return type:dropbox.team.MembersGetInfoV2Result
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersGetInfoError
team_members_list(limit=1000, include_removed=False)

Lists members of a team. Permission : Team information.

Route attributes:
scope: members.read
Parameters:
  • limit (int) – Number of results to return per call.
  • include_removed (bool) – Whether to return removed members.
Return type:

dropbox.team.MembersListResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersListError
team_members_list_continue(cursor)

Once a cursor has been retrieved from team_members_list(), use this to paginate through all team members. Permission : Team information.

Route attributes:
scope: members.read
Parameters:cursor (str) – Indicates from what point to get the next set of members.
Return type:dropbox.team.MembersListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersListContinueError
team_members_list_continue_v2(cursor)

Once a cursor has been retrieved from team_members_list_v2(), use this to paginate through all team members. Permission : Team information.

Route attributes:
scope: members.read
Parameters:cursor (str) – Indicates from what point to get the next set of members.
Return type:dropbox.team.MembersListV2Result
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersListContinueError
team_members_list_v2(limit=1000, include_removed=False)

Lists members of a team. Permission : Team information.

Route attributes:
scope: members.read
Parameters:
  • limit (int) – Number of results to return per call.
  • include_removed (bool) – Whether to return removed members.
Return type:

dropbox.team.MembersListV2Result

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersListError
team_members_move_former_member_files(user, transfer_dest_id, transfer_admin_id)

Moves removed member’s files to a different member. This endpoint initiates an asynchronous job. To obtain the final result of the job, the client should periodically poll team_members_move_former_member_files_job_status_check(). Permission : Team member management.

Route attributes:
scope: members.write
Parameters:
Return type:

dropbox.team.LaunchEmptyResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersTransferFormerMembersFilesError
team_members_move_former_member_files_job_status_check(async_job_id)

Once an async_job_id is returned from team_members_move_former_member_files() , use this to poll the status of the asynchronous request. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.PollEmptyResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.PollError
team_members_recover(user)

Recover a deleted member. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account.

Route attributes:
scope: members.delete
Parameters:user (dropbox.team.UserSelectorArg) – Identity of user to recover.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersRecoverError
team_members_remove(user, wipe_data=True, transfer_dest_id=None, transfer_admin_id=None, keep_account=False, retain_team_shares=False)

Removes a member from a team. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account. Accounts can be recovered via team_members_recover() for a 7 day period or until the account has been permanently deleted or transferred to another account (whichever comes first). Calling team_members_add() while a user is still recoverable on your team will return with MemberAddResult.user_already_on_team. Accounts can have their files transferred via the admin console for a limited time, based on the version history length associated with the team (180 days for most teams). This endpoint may initiate an asynchronous job. To obtain the final result of the job, the client should periodically poll team_members_remove_job_status_get().

Route attributes:
scope: members.delete
:param Nullable[dropbox.team.UserSelectorArg] transfer_dest_id:
If provided, files from the deleted member account will be transferred to this user.
:param Nullable[dropbox.team.UserSelectorArg]
transfer_admin_id: If provided, errors during the transfer process will be sent via email to this user. If the transfer_dest_id argument was provided, then this argument must be provided as well.
Parameters:
  • keep_account (bool) – Downgrade the member to a Basic account. The user will retain the email address associated with their Dropbox account and data in their account that is not restricted to team members. In order to keep the account the argument wipe_data should be set to False.
  • retain_team_shares (bool) – If provided, allows removed users to keep access to Dropbox folders (not Dropbox Paper folders) already explicitly shared with them (not via a group) when they are downgraded to a Basic account. Users will not retain access to folders that do not allow external sharing. In order to keep the sharing relationships, the arguments wipe_data should be set to False and keep_account should be set to True.
Return type:

dropbox.team.LaunchEmptyResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersRemoveError
team_members_remove_job_status_get(async_job_id)

Once an async_job_id is returned from team_members_remove() , use this to poll the status of the asynchronous request. Permission : Team member management.

Route attributes:
scope: members.delete
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.PollEmptyResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.PollError
team_members_secondary_emails_add(new_secondary_emails)

Add secondary emails to users. Permission : Team member management. Emails that are on verified domains will be verified automatically. For each email address not on a verified domain a verification email will be sent.

Route attributes:
scope: members.write
:param List[dropbox.team.UserSecondaryEmailsArg]
new_secondary_emails: List of users and secondary emails to add.
Return type:dropbox.team.AddSecondaryEmailsResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.AddSecondaryEmailsError
team_members_secondary_emails_delete(emails_to_delete)

Delete secondary emails from users Permission : Team member management. Users will be notified of deletions of verified secondary emails at both the secondary email and their primary email.

Route attributes:
scope: members.write
:param List[dropbox.team.UserSecondaryEmailsArg]
emails_to_delete: List of users and their secondary emails to delete.
Return type:dropbox.team.DeleteSecondaryEmailsResult
team_members_secondary_emails_resend_verification_emails(emails_to_resend)

Resend secondary email verification emails. Permission : Team member management.

Route attributes:
scope: members.write
:param List[dropbox.team.UserSecondaryEmailsArg]
emails_to_resend: List of users and secondary emails to resend verification emails to.
Return type:dropbox.team.ResendVerificationEmailResult
team_members_send_welcome_email(arg)

Sends welcome email to pending team member. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account. No-op if team member is not pending.

Route attributes:
scope: members.write
Parameters:arg (dropbox.team.UserSelectorArg) – Argument for selecting a single user, either by team_member_id, external_id or email.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersSendWelcomeError
team_members_set_admin_permissions(user, new_role)

Updates a team member’s permissions. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:
Return type:

dropbox.team.MembersSetPermissionsResult

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersSetPermissionsError
team_members_set_admin_permissions_v2(user, new_roles=None)

Updates a team member’s permissions. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:
  • user (dropbox.team.UserSelectorArg) – Identity of user whose role will be set.
  • new_roles (Nullable[List[str]]) – The new roles for the member. Send empty list to make user member only. For now, only up to one role is allowed.
Return type:

dropbox.team.MembersSetPermissions2Result

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersSetPermissions2Error
team_members_set_profile(user, new_email=None, new_external_id=None, new_given_name=None, new_surname=None, new_persistent_id=None, new_is_directory_restricted=None)

Updates a team member’s profile. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:
  • user (dropbox.team.UserSelectorArg) – Identity of user whose profile will be set.
  • new_email (Nullable[str]) – New email for member.
  • new_external_id (Nullable[str]) – New external ID for member.
  • new_given_name (Nullable[str]) – New given name for member.
  • new_surname (Nullable[str]) – New surname for member.
  • new_persistent_id (Nullable[str]) – New persistent ID. This field only available to teams using persistent ID SAML configuration.
  • new_is_directory_restricted (Nullable[bool]) – New value for whether the user is a directory restricted user.
Return type:

dropbox.team.TeamMemberInfo

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersSetProfileError
team_members_set_profile_photo(user, photo)

Updates a team member’s profile photo. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:
  • user (dropbox.team.UserSelectorArg) – Identity of the user whose profile photo will be set.
  • photo (dropbox.team.PhotoSourceArg) – Image to set as the member’s new profile photo.
Return type:

dropbox.team.TeamMemberInfo

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersSetProfilePhotoError
team_members_set_profile_photo_v2(user, photo)

Updates a team member’s profile photo. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:
  • user (dropbox.team.UserSelectorArg) – Identity of the user whose profile photo will be set.
  • photo (dropbox.team.PhotoSourceArg) – Image to set as the member’s new profile photo.
Return type:

dropbox.team.TeamMemberInfoV2Result

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersSetProfilePhotoError
team_members_set_profile_v2(user, new_email=None, new_external_id=None, new_given_name=None, new_surname=None, new_persistent_id=None, new_is_directory_restricted=None)

Updates a team member’s profile. Permission : Team member management.

Route attributes:
scope: members.write
Parameters:
  • user (dropbox.team.UserSelectorArg) – Identity of user whose profile will be set.
  • new_email (Nullable[str]) – New email for member.
  • new_external_id (Nullable[str]) – New external ID for member.
  • new_given_name (Nullable[str]) – New given name for member.
  • new_surname (Nullable[str]) – New surname for member.
  • new_persistent_id (Nullable[str]) – New persistent ID. This field only available to teams using persistent ID SAML configuration.
  • new_is_directory_restricted (Nullable[bool]) – New value for whether the user is a directory restricted user.
Return type:

dropbox.team.TeamMemberInfoV2Result

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.MembersSetProfileError
team_members_suspend(user, wipe_data=True)

Suspend a member from a team. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account.

Route attributes:
scope: members.write
Parameters:wipe_data (bool) – If provided, controls if the user’s data will be deleted on their linked devices.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersSuspendError
team_members_unsuspend(user)

Unsuspend a member from a team. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account.

Route attributes:
scope: members.write
Parameters:user (dropbox.team.UserSelectorArg) – Identity of user to unsuspend.
Return type:None
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.MembersUnsuspendError
team_namespaces_list(limit=1000)

Returns a list of all team-accessible namespaces. This list includes team folders, shared folders containing team members, team members’ home namespaces, and team members’ app folders. Home namespaces and app folders are always owned by this team or members of the team, but shared folders may be owned by other users or other teams. Duplicates may occur in the list.

Route attributes:
scope: team_data.member
Parameters:limit (int) – Specifying a value here has no effect.
Return type:dropbox.team.TeamNamespacesListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamNamespacesListError
team_namespaces_list_continue(cursor)

Once a cursor has been retrieved from team_namespaces_list(), use this to paginate through all team-accessible namespaces. Duplicates may occur in the list.

Route attributes:
scope: team_data.member
Parameters:cursor (str) – Indicates from what point to get the next set of team-accessible namespaces.
Return type:dropbox.team.TeamNamespacesListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamNamespacesListContinueError
team_properties_template_add(name, description, fields)

Permission : Team member file access.

Route attributes:
scope: files.team_metadata.write
Return type:dropbox.team.AddTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ModifyTemplateError
team_properties_template_get(template_id)

Permission : Team member file access. The scope for the route is files.team_metadata.write.

Route attributes:
scope: files.team_metadata.write
Parameters:template_id (str) – An identifier for template added by route See team_templates_add_for_user() or team_templates_add_for_team().
Return type:dropbox.team.GetTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TemplateError
team_properties_template_list()

Permission : Team member file access. The scope for the route is files.team_metadata.write.

Route attributes:
scope: files.team_metadata.write
Return type:dropbox.team.ListTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TemplateError
team_properties_template_update(template_id, name=None, description=None, add_fields=None)

Permission : Team member file access.

Route attributes:
scope: files.team_metadata.write
Parameters:
  • template_id (str) – An identifier for template added by See team_templates_add_for_user() or team_templates_add_for_team().
  • name (Nullable[str]) – A display name for the template. template names can be up to 256 bytes.
  • description (Nullable[str]) – Description for the new template. Template descriptions can be up to 1024 bytes.
:param Nullable[List[dropbox.team.PropertyFieldTemplate]]
add_fields: Property field templates to be added to the group template. There can be up to 32 properties in a single template.
Return type:dropbox.team.UpdateTemplateResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.ModifyTemplateError
team_reports_get_activity(start_date=None, end_date=None)

Retrieves reporting data about a team’s user activity. Deprecated: Will be removed on July 1st 2021.

Route attributes:
scope: team_info.read
Parameters:
  • start_date (Nullable[datetime]) – Optional starting date (inclusive). If start_date is None or too long ago, this field will be set to 6 months ago.
  • end_date (Nullable[datetime]) – Optional ending date (exclusive).
Return type:

dropbox.team.GetActivityReport

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.DateRangeError
team_reports_get_devices(start_date=None, end_date=None)

Retrieves reporting data about a team’s linked devices. Deprecated: Will be removed on July 1st 2021.

Route attributes:
scope: team_info.read
Parameters:
  • start_date (Nullable[datetime]) – Optional starting date (inclusive). If start_date is None or too long ago, this field will be set to 6 months ago.
  • end_date (Nullable[datetime]) – Optional ending date (exclusive).
Return type:

dropbox.team.GetDevicesReport

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.DateRangeError
team_reports_get_membership(start_date=None, end_date=None)

Retrieves reporting data about a team’s membership. Deprecated: Will be removed on July 1st 2021.

Route attributes:
scope: team_info.read
Parameters:
  • start_date (Nullable[datetime]) – Optional starting date (inclusive). If start_date is None or too long ago, this field will be set to 6 months ago.
  • end_date (Nullable[datetime]) – Optional ending date (exclusive).
Return type:

dropbox.team.GetMembershipReport

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.DateRangeError
team_reports_get_storage(start_date=None, end_date=None)

Retrieves reporting data about a team’s storage usage. Deprecated: Will be removed on July 1st 2021.

Route attributes:
scope: team_info.read
Parameters:
  • start_date (Nullable[datetime]) – Optional starting date (inclusive). If start_date is None or too long ago, this field will be set to 6 months ago.
  • end_date (Nullable[datetime]) – Optional ending date (exclusive).
Return type:

dropbox.team.GetStorageReport

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.DateRangeError
team_sharing_allowlist_add(domains=None, emails=None)

Endpoint adds Approve List entries. Changes are effective immediately. Changes are committed in transaction. In case of single validation error - all entries are rejected. Valid domains (RFC-1034/5) and emails (RFC-5322/822) are accepted. Added entries cannot overflow limit of 10000 entries per team. Maximum 100 entries per call is allowed.

Route attributes:
scope: team_info.write
Parameters:
  • domains (Nullable[List[str]]) – List of domains represented by valid string representation (RFC-1034/5).
  • emails (Nullable[List[str]]) – List of emails represented by valid string representation (RFC-5322/822).
Return type:

dropbox.team.SharingAllowlistAddResponse

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.SharingAllowlistAddError
team_sharing_allowlist_list(limit=1000)

Lists Approve List entries for given team, from newest to oldest, returning up to limit entries at a time. If there are more than limit entries associated with the current team, more can be fetched by passing the returned cursor to team_sharing_allowlist_list_continue().

Route attributes:
scope: team_info.read
Parameters:limit (int) – The number of entries to fetch at one time.
Return type:dropbox.team.SharingAllowlistListResponse
team_sharing_allowlist_list_continue(cursor)

Lists entries associated with given team, starting from a the cursor. See team_sharing_allowlist_list().

Route attributes:
scope: team_info.read
Parameters:cursor (str) – The cursor returned from a previous call to team_sharing_allowlist_list() or team_sharing_allowlist_list_continue().
Return type:dropbox.team.SharingAllowlistListResponse
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.SharingAllowlistListContinueError
team_sharing_allowlist_remove(domains=None, emails=None)

Endpoint removes Approve List entries. Changes are effective immediately. Changes are committed in transaction. In case of single validation error - all entries are rejected. Valid domains (RFC-1034/5) and emails (RFC-5322/822) are accepted. Entries being removed have to be present on the list. Maximum 1000 entries per call is allowed.

Route attributes:
scope: team_info.write
Parameters:
  • domains (Nullable[List[str]]) – List of domains represented by valid string representation (RFC-1034/5).
  • emails (Nullable[List[str]]) – List of emails represented by valid string representation (RFC-5322/822).
Return type:

dropbox.team.SharingAllowlistRemoveResponse

Raises:

exceptions.ApiError

If this raises, ApiError will contain:
dropbox.team.SharingAllowlistRemoveError
team_team_folder_activate(team_folder_id)

Sets an archived team folder’s status to active. Permission : Team member file access.

Route attributes:
scope: team_data.content.write
Parameters:team_folder_id (str) – The ID of the team folder.
Return type:dropbox.team.TeamFolderMetadata
team_team_folder_archive(team_folder_id, force_async_off=False)

Sets an active team folder’s status to archived and removes all folder and file members. This endpoint cannot be used for teams that have a shared team space. Permission : Team member file access.

Route attributes:
scope: team_data.content.write
Parameters:force_async_off (bool) – Whether to force the archive to happen synchronously.
Return type:dropbox.team.TeamFolderArchiveLaunch
team_team_folder_archive_check(async_job_id)

Returns the status of an asynchronous job for archiving a team folder. Permission : Team member file access.

Route attributes:
scope: team_data.content.write
Parameters:async_job_id (str) – Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Return type:dropbox.team.TeamFolderArchiveJobStatus
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.PollError
team_team_folder_create(name, sync_setting=None)

Creates a new, active, team folder with no members. This endpoint can only be used for teams that do not already have a shared team space. Permission : Team member file access.

Route attributes:
scope: team_data.content.write
Parameters:name (str) – Name for the new team folder.
:param Nullable[dropbox.team.SyncSettingArg] sync_setting: The
sync setting to apply to this team folder. Only permitted if the team has team selective sync enabled.
Return type:dropbox.team.TeamFolderMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamFolderCreateError
team_team_folder_get_info(team_folder_ids)

Retrieves metadata for team folders. Permission : Team member file access.

Route attributes:
scope: team_data.content.read
Parameters:team_folder_ids (List[str]) – The list of team folder IDs.
Return type:List[dropbox.team.TeamFolderGetInfoItem]
team_team_folder_list(limit=1000)

Lists all team folders. Permission : Team member file access.

Route attributes:
scope: team_data.content.read
Parameters:limit (int) – The maximum number of results to return per request.
Return type:dropbox.team.TeamFolderListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamFolderListError
team_team_folder_list_continue(cursor)

Once a cursor has been retrieved from team_team_folder_list(), use this to paginate through all team folders. Permission : Team member file access.

Route attributes:
scope: team_data.content.read
Parameters:cursor (str) – Indicates from what point to get the next set of team folders.
Return type:dropbox.team.TeamFolderListResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamFolderListContinueError
team_team_folder_permanently_delete(team_folder_id)

Permanently deletes an archived team folder. This endpoint cannot be used for teams that have a shared team space. Permission : Team member file access.

Route attributes:
scope: team_data.content.write
Parameters:team_folder_id (str) – The ID of the team folder.
Return type:None
team_team_folder_rename(team_folder_id, name)

Changes an active team folder’s name. Permission : Team member file access.

Route attributes:
scope: team_data.content.write
Parameters:name (str) – New team folder name.
Return type:dropbox.team.TeamFolderMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamFolderRenameError
team_team_folder_update_sync_settings(team_folder_id, sync_setting=None, content_sync_settings=None)

Updates the sync settings on a team folder or its contents. Use of this endpoint requires that the team has team selective sync enabled.

Route attributes:
scope: team_data.content.write
:param Nullable[dropbox.team.SyncSettingArg] sync_setting: Sync
setting to apply to the team folder itself. Only meaningful if the team folder is not a shared team root.
:param Nullable[List[dropbox.team.ContentSyncSettingArg]]
content_sync_settings: Sync settings to apply to contents of this team folder.
Return type:dropbox.team.TeamFolderMetadata
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TeamFolderUpdateSyncSettingsError
team_token_get_authenticated_admin()

Returns the member profile of the admin who generated the team access token used to make the call.

Route attributes:
scope: team_info.read
Return type:dropbox.team.TokenGetAuthenticatedAdminResult
Raises:exceptions.ApiError
If this raises, ApiError will contain:
dropbox.team.TokenGetAuthenticatedAdminError
with_path_root(path_root)

Creates a clone of the Dropbox instance with the Dropbox-API-Path-Root header as the appropriate serialized instance of PathRoot.

For more information, see https://www.dropbox.com/developers/reference/namespace-guide#pathrootmodes

Parameters:path_root (PathRoot) – instance of PathRoot to serialize into the headers field
Returns:A :class: Dropbox
Return type:Dropbox
dropbox.dropbox_client.create_session(max_connections=8, proxies=None, ca_certs=None)

Creates a session object that can be used by multiple Dropbox and DropboxTeam instances. This lets you share a connection pool amongst them, as well as proxy parameters.

Parameters:
  • max_connections (int) – Maximum connection pool size.
  • proxies (dict) – See the requests module for more details.
Return type:

requests.sessions.Session. See the requests module for more details.