namespace sharing
import async
import common
import files
import team_common
import users_common
alias DropboxId = String(min_length=1)
union AccessLevel
"Defines the access levels for collaborators."
owner
"The collaborator is the owner of the shared folder. Owners can
view and edit the shared folder as well as set the folder's
policies using :route:`update_folder_policy`."
editor
"The collaborator can both view and edit the shared folder."
viewer
"The collaborator can only view the shared folder."
viewer_no_comment
"The collaborator can only view the shared folder and does
not have any access to comments."
traverse
"The collaborator can only view the shared folder that they have
access to."
no_access
"If there is a Righteous Link on the folder which grants access
and the user has visited such link, they are allowed to perform
certain action (i.e. add themselves to the folder) via the link
access even though the user themselves are not a member on the
shared folder yet."
struct FolderPolicy
"A set of policies governing membership and privileges for a shared
folder."
member_policy MemberPolicy?
"Who can be a member of this shared folder, as set on the folder itself.
The effective policy may differ from this value if the team-wide policy
is more restrictive. Present only if the folder is owned by a team."
resolved_member_policy MemberPolicy?
"Who can be a member of this shared folder, taking into account both the
folder and the team-wide policy. This value may differ from that of
member_policy if the team-wide policy is more restrictive than the folder
policy. Present only if the folder is owned by a team."
acl_update_policy AclUpdatePolicy
"Who can add and remove members from this shared folder."
shared_link_policy SharedLinkPolicy
"Who links can be shared with."
viewer_info_policy ViewerInfoPolicy?
"Who can enable/disable viewer info for this shared folder."
example default
member_policy = anyone
resolved_member_policy = team
acl_update_policy = owner
shared_link_policy = anyone
union FolderAction
"Actions that may be taken on shared folders."
change_options
"Change folder options, such as who can be invited to join the folder."
disable_viewer_info
"Disable viewer information for this folder."
edit_contents
"Change or edit contents of the folder."
enable_viewer_info
"Enable viewer information on the folder."
invite_editor
"Invite a user or group to join the folder with read and write permission."
invite_viewer
"Invite a user or group to join the folder with read permission."
invite_viewer_no_comment
"Invite a user or group to join the folder with read permission but no comment permissions."
relinquish_membership
"Relinquish one's own membership in the folder."
unmount
"Unmount the folder."
unshare
"Stop sharing this folder."
leave_a_copy
"Keep a copy of the contents upon leaving or being kicked from the folder."
share_link
"Use create_link instead."
create_link
"Create a shared link for folder."
set_access_inheritance
"Set whether the folder inherits permissions from its parent."
struct FolderPermission
"Whether the user is allowed to take the action on the shared folder."
action FolderAction
"The action that the user may wish to take on the folder."
allow Boolean
"True if the user is allowed to take the action."
reason PermissionDeniedReason?
"The reason why the user is denied the permission. Not present if the action
is allowed, or if no reason is available."
example default
action = edit_contents
allow = false
reason = user_not_same_team_as_owner
union MemberPolicy
"Policy governing who can be a member of a shared folder. Only applicable
to folders owned by a user on a team."
team
"Only a teammate can become a member."
anyone
"Anyone can become a member."
union MemberAction
"Actions that may be taken on members of a shared folder."
leave_a_copy
"Allow the member to keep a copy of the folder when removing."
make_editor
"Make the member an editor of the folder."
make_owner
"Make the member an owner of the folder."
make_viewer
"Make the member a viewer of the folder."
make_viewer_no_comment
"Make the member a viewer of the folder without commenting permissions."
remove
"Remove the member from the folder."
struct MemberPermission
"Whether the user is allowed to take the action on the associated member."
action MemberAction
"The action that the user may wish to take on the member."
allow Boolean
"True if the user is allowed to take the action."
reason PermissionDeniedReason?
"The reason why the user is denied the permission. Not present if the action is allowed."
example default
action = make_owner
allow = false
reason = target_is_indirect_member
union PermissionDeniedReason
"Possible reasons the user is denied a permission."
user_not_same_team_as_owner
"User is not on the same team as the folder owner."
user_not_allowed_by_owner
"User is prohibited by the owner from taking the action."
target_is_indirect_member
"Target is indirectly a member of the folder, for example by being part of a group."
target_is_owner
"Target is the owner of the folder."
target_is_self
"Target is the user itself."
target_not_active
"Target is not an active member of the team."
folder_is_limited_team_folder
"Folder is team folder for a limited team."
owner_not_on_team
"The content owner needs to be on a Dropbox team to perform this action."
permission_denied
"The user does not have permission to perform this action on the link."
restricted_by_team
"The user's team policy prevents performing this action on the link."
user_account_type
"The user's account type does not support this action."
user_not_on_team
"The user needs to be on a Dropbox team to perform this action."
folder_is_inside_shared_folder
"Folder is inside of another shared folder."
restricted_by_parent_folder
"Policy cannot be changed due to restrictions from parent folder."
insufficient_plan InsufficientPlan
struct InsufficientPlan
message String
"A message to tell the user to upgrade in order to support expected action."
upsell_url String?
"A URL to send the user to in order to obtain the account type they need, e.g. upgrading.
Absent if there is no action the user can take to upgrade."
union AclUpdatePolicy
"Who can change a shared folder's access control list (ACL). In other words, who can add,
remove, or change the privileges of members."
owner
"Only the owner can update the ACL."
editors
"Any editor can update the ACL. This may be further restricted to
editors on the same team."
union SharedLinkPolicy
"Who can view shared links in this folder."
anyone
"Links can be shared with anyone."
team
"Links can be shared with anyone on the same team as the owner."
members
"Links can only be shared among members of the shared folder."
struct MembershipInfo
"The information about a member of the shared content."
access_type AccessLevel
"The access type for this member. It contains inherited access type from parent folder,
and acquired access type from this folder."
permissions List(MemberPermission)?
"The permissions that requesting user has on this member. The set of
permissions corresponds to the MemberActions in the request."
initials String?
"Never set."
is_inherited Boolean = false
"True if the member has access from a parent folder."
example default
access_type = owner
permissions = []
initials = "JD"
is_inherited = false
struct UserInfo
"Basic information about a user. Use :route:`users.get_account` and
:route:`users.get_account_batch` to obtain more detailed information."
account_id users_common.AccountId
"The account ID of the user."
email String
"Email address of user."
display_name String
"The display name of the user."
same_team Boolean
"If the user is in the same team as current user."
team_member_id String?
"The team member ID of the shared folder member. Only present if
:field:`same_team` is true."
example default
account_id = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
same_team = true
team_member_id = "dbmid:abcd1234"
email = "bob@example.com"
display_name = "Robert Smith"
struct UserMembershipInfo extends MembershipInfo
"The information about a user member of the shared content."
user UserInfo
"The account information for the membership user."
example default
user = default
access_type = owner
permissions = []
union InviteeInfo
"Information about the recipient of a shared content invitation."
email common.EmailAddress
"Email address of invited user."
example default
email = "jessica@example.com"
struct InviteeMembershipInfo extends MembershipInfo
"Information about an invited member of a shared content."
invitee InviteeInfo
"Recipient of the invitation."
user UserInfo?
"The user this invitation is tied to, if available."
example default
invitee = default
access_type = viewer
permissions = []
struct GroupInfo extends team_common.GroupSummary
"The information about a group. Groups is a way to manage a list of users
who need same access permission to the shared folder."
group_type team_common.GroupType
"The type of group."
is_member Boolean
"If the current user is a member of the group."
is_owner Boolean
"If the current user is an owner of the group."
same_team Boolean
"If the group is owned by the current user's team."
example default
group_name = "Test group"
group_id = "g:e2db7665347abcd600000000001a2b3c"
member_count = 10
group_management_type = user_managed
group_type = user_managed
is_member = false
is_owner = false
same_team = true
struct GroupMembershipInfo extends MembershipInfo
"The information about a group member of the shared content."
group GroupInfo
"The information about the membership group."
example default
group = default
access_type = editor
permissions = []
struct SharedFolderMetadataBase
"Properties of the shared folder."
access_type AccessLevel
"The current user's access level for this shared folder."
is_inside_team_folder Boolean
"Whether this folder is inside of a team folder."
is_team_folder Boolean
"Whether this folder is a
:link:`team folder https://www.dropbox.com/en/help/986`."
owner_display_names List(String)?
"The display names of the users that own the folder. If the folder is
part of a team folder, the display names of the team admins are also
included. Absent if the owner display names cannot be fetched."
owner_team users.Team?
"The team that owns the folder. This field is not present if the folder
is not owned by a team."
parent_shared_folder_id common.SharedFolderId?
"The ID of the parent shared folder. This field is present only if the
folder is contained within another shared folder."
path_display String?
"The full path of this shared folder. Absent for unmounted folders."
path_lower String?
"The lower-cased full path of this shared folder. Absent for unmounted folders."
parent_folder_name String?
"Display name for the parent folder."
example default
access_type = owner
is_inside_team_folder = false
is_team_folder = false
owner_display_names = ["Jane Doe"]
owner_team = default
parent_folder_name = "Parent Shared Folder"
union AccessInheritance
"Information about the inheritance policy of a shared folder."
inherit
"The shared folder inherits its members from the parent folder."
no_inherit
"The shared folder does not inherit its members from the parent folder."
# NOTE: If you modify this struct, also modify InternalSharedFolderMetadata,
# which is used by mobile
struct SharedFolderMetadata extends SharedFolderMetadataBase
"The metadata which includes basic information about the shared folder."
link_metadata SharedContentLinkMetadata?
"The metadata of the shared content link to this shared folder. Absent if there is no
link on the folder. This is for an unreleased feature so it may not be returned yet."
name String
"The name of the this shared folder."
permissions List(FolderPermission)?
"Actions the current user may perform on the folder and its contents.
The set of permissions corresponds to the FolderActions in the request."
policy FolderPolicy
"Policies governing this shared folder."
preview_url String
"URL for displaying a web preview of the shared folder."
shared_folder_id common.SharedFolderId
"The ID of the shared folder."
time_invited common.DropboxTimestamp
"Timestamp indicating when the current user was invited to this shared folder."
access_inheritance AccessInheritance = inherit
"Whether the folder inherits its members from its parent."
example default
path_lower = "/dir"
link_metadata = default
name = "dir"
shared_folder_id = "84528192421"
permissions = []
access_type = owner
is_inside_team_folder = false
is_team_folder = false
policy = default
time_invited = "2016-01-20T00:00:00Z"
preview_url = "https://www.dropbox.com/scl/fo/fir9vjelf"
access_inheritance = inherit
union SharedFolderAccessError
"There is an error accessing the shared folder."
invalid_id
"This shared folder ID is invalid."
not_a_member
"The user is not a member of the shared folder
thus cannot access it."
invalid_member
"The user does not exist or their account is disabled."
email_unverified
"Never set."
unmounted
"The shared folder is unmounted."
struct MemberAccessLevelResult
"Contains information about a member's access level to content after an operation."
access_level AccessLevel?
"The member still has this level of access to the content through a parent folder."
warning String?
"A localized string with additional information about why the user
has this access level to the content."
access_details List(ParentFolderAccessInfo)?
"The parent folders that a member has access to. The field is present if the user
has access to the first parent folder where the member gains access."
example default
struct ParentFolderAccessInfo
"Contains information about a parent folder that a member has access to."
folder_name String
"Display name for the folder."
shared_folder_id common.SharedFolderId
"The identifier of the parent shared folder."
permissions List(MemberPermission)
"The user's permissions for the parent shared folder."
path String
"The full path to the parent shared folder relative to the acting user's root."
example default
folder_name = "Shared Folder"
shared_folder_id = "84528192421"
permissions = []
path = "/Shared Folder"
# --
route list_folders(ListFoldersArgs, ListFoldersResult, Void)
"Return the list of all shared folders the current user has access to."
attrs
scope = "sharing.read"
struct ListFoldersArgs
limit UInt32(min_value=1, max_value=1000) = 1000
"The maximum number of results to return per request."
actions List(FolderAction)?
"A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the
response's :field:`SharedFolderMetadata.permissions` field describing the actions the
authenticated user can perform on the folder."
example default
limit = 100
actions = []
struct ListFoldersResult
"Result for :route:`list_folders` or :route:`list_mountable_folders`, depending on which
endpoint was requested.
Unmounted shared folders can be identified by the absence of
:field:`SharedFolderMetadata.path_lower`."
entries List(SharedFolderMetadata)
"List of all shared folders the authenticated user has access to."
cursor String?
"Present if there are additional shared folders that have not been returned yet. Pass the
cursor into the corresponding continue endpoint (either :route:`list_folders/continue`
or :route:`list_mountable_folders/continue`) to list additional folders."
example default
entries = [default]
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
# --
route list_folders/continue(ListFoldersContinueArg, ListFoldersResult, ListFoldersContinueError)
"Once a cursor has been retrieved from :route:`list_folders`, use this to paginate through all
shared folders. The cursor must come from a previous call to :route:`list_folders` or
:route:`list_folders/continue`."
attrs
scope = "sharing.read"
struct ListFoldersContinueArg
cursor String
"The cursor returned by the previous API call specified in the endpoint description."
example default
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
union ListFoldersContinueError
invalid_cursor
":field:`ListFoldersContinueArg.cursor` is invalid."
# --
route list_mountable_folders(ListFoldersArgs, ListFoldersResult, Void)
"Return the list of all shared folders the current user can mount or unmount."
attrs
scope = "sharing.read"
# --
route list_mountable_folders/continue(ListFoldersContinueArg, ListFoldersResult, ListFoldersContinueError)
"Once a cursor has been retrieved from :route:`list_mountable_folders`, use this to paginate through all
mountable shared folders. The cursor must come from a previous call to :route:`list_mountable_folders` or
:route:`list_mountable_folders/continue`."
attrs
scope = "sharing.read"
# --
route get_folder_metadata(GetMetadataArgs, SharedFolderMetadata, SharedFolderAccessError)
"Returns shared folder metadata by its folder ID."
attrs
select_admin_mode = "whole_team"
scope = "sharing.read"
struct GetMetadataArgs
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
actions List(FolderAction)?
"A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the
response's :field:`SharedFolderMetadata.permissions` field describing the actions the
authenticated user can perform on the folder."
example default
shared_folder_id = "84528192421"
actions = []
# --
route list_folder_members(ListFolderMembersArgs, SharedFolderMembers, SharedFolderAccessError)
"Returns shared folder membership by its folder ID."
attrs
select_admin_mode = "whole_team"
scope = "sharing.read"
struct ListFolderMembersCursorArg
actions List(MemberAction)?
"This is a list indicating whether each returned member will include a boolean value
:field:`MemberPermission.allow` that describes whether the current user can perform
the MemberAction on the member."
limit UInt32(min_value=1, max_value=1000) = 1000
"The maximum number of results that include members, groups and invitees to return per request."
example default
actions = []
limit = 10
struct ListFolderMembersArgs extends ListFolderMembersCursorArg
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
example default
shared_folder_id = "84528192421"
actions = []
limit = 10
struct SharedFolderMembers
"Shared folder user and group membership."
users List(UserMembershipInfo)
"The list of user members of the shared folder."
groups List(GroupMembershipInfo)
"The list of group members of the shared folder."
invitees List(InviteeMembershipInfo)
"The list of invitees to the shared folder."
cursor String?
"Present if there are additional shared folder members that have not been returned yet. Pass
the cursor into :route:`list_folder_members/continue` to list additional members."
example default
users = [default]
groups = [default]
invitees = [default]
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
# --
route list_folder_members/continue(ListFolderMembersContinueArg, SharedFolderMembers, ListFolderMembersContinueError)
"Once a cursor has been retrieved from :route:`list_folder_members`, use this to paginate
through all shared folder members."
attrs
select_admin_mode = "whole_team"
scope = "sharing.read"
struct ListFolderMembersContinueArg
cursor String
"The cursor returned by your last call to :route:`list_folder_members` or
:route:`list_folder_members/continue`."
example default
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
union ListFolderMembersContinueError
access_error SharedFolderAccessError
invalid_cursor
":field:`ListFolderMembersContinueArg.cursor` is invalid."
# --
route share_folder(ShareFolderArg, ShareFolderLaunch, ShareFolderError )
"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 :field:`ShareFolderLaunch.async_job_id` is returned, you'll need to
call :route:`check_share_job_status` until the action completes to get the
metadata for the folder."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
# As of 2017-05, there are three kinds of arg:
# ShareFolderArg: The public stable version. We cannot make backwards-incompatible changes at all.
# ShareFolderInternalArg: The private stable version. We cannot make backwards-incompatible changes
# unless we are sure no clients in the wild are using the endpoint.
# AlphaShareFolderArg: The private experimental version. We can do what we want as long as it
# doesn't break web.
struct ShareFolderArgBase
acl_update_policy AclUpdatePolicy?
"Who can add and remove members of this shared folder."
force_async Boolean = false
"Whether to force the share to happen asynchronously."
member_policy MemberPolicy?
"Who can be a member of this shared folder. Only applicable if the
current user is on a team."
path files.WritePathOrId
"The path or the file id to the folder to share. If it does not exist,
then a new one is created."
shared_link_policy SharedLinkPolicy?
"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
:field:`SharedLinkPolicy.members`."
viewer_info_policy ViewerInfoPolicy?
"Who can enable/disable viewer info for this shared folder."
access_inheritance AccessInheritance = inherit
"The access inheritance settings for the folder."
example default
path = "/example/workspace"
struct ShareFolderArg extends ShareFolderArgBase
actions List(FolderAction)?
"A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the
response's :field:`SharedFolderMetadata.permissions` field describing the actions the
authenticated user can perform on the folder."
link_settings LinkSettings?
"Settings on the link for this folder."
example default
path = "/example/workspace"
member_policy = team
acl_update_policy = editors
shared_link_policy = members
union ShareFolderErrorBase
email_unverified
"This user's email address is not verified. This functionality is only
available on accounts with a verified email address. Users can verify
their email address :link:`here https://www.dropbox.com/help/317`."
bad_path SharePathError
":field:`ShareFolderArg.path` is invalid."
team_policy_disallows_member_policy
"Team policy is more restrictive than :field:`ShareFolderArg.member_policy`."
disallowed_shared_link_policy
"The current user's account is not allowed to select the specified
:field:`ShareFolderArg.shared_link_policy`."
union ShareFolderError extends ShareFolderErrorBase
no_permission
"The current user does not have permission to perform this action."
union SharePathError
is_file
"A file is at the specified path."
inside_shared_folder
"We do not support sharing a folder inside a shared folder."
contains_shared_folder
"We do not support shared folders that contain shared folders."
contains_app_folder
"We do not support shared folders that contain app folders."
contains_team_folder
"We do not support shared folders that contain team folders."
is_app_folder
"We do not support sharing an app folder."
inside_app_folder
"We do not support sharing a folder inside an app folder."
is_public_folder
"A public folder can't be shared this way. Use a public link instead."
inside_public_folder
"A folder inside a public folder can't be shared this way. Use a public
link instead."
already_shared SharedFolderMetadata
"Folder is already shared. Contains metadata about the existing shared folder."
invalid_path
"Path is not valid."
is_osx_package
"We do not support sharing a Mac OS X package."
inside_osx_package
"We do not support sharing a folder inside a Mac OS X package."
is_vault
"We do not support sharing the Vault folder."
is_vault_locked
"We do not support sharing a folder inside a locked Vault."
is_family
"We do not support sharing the Family folder."
# --
union_closed ShareFolderJobStatus extends async.PollResultBase
complete SharedFolderMetadata
"The share job has finished. The value is the metadata for the folder."
failed ShareFolderError
example default
complete = default
union_closed ShareFolderLaunch extends async.LaunchResultBase
complete SharedFolderMetadata
example default
complete = default
route check_share_job_status(async.PollArg, ShareFolderJobStatus, async.PollError)
"Returns the status of an asynchronous job for sharing a folder."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
union_closed JobStatus extends async.PollResultBase
complete
"The asynchronous job has finished."
failed JobError
"The asynchronous job returned an error."
# --
union SharedFolderMemberError
invalid_dropbox_id
"The target dropbox_id is invalid."
not_a_member
"The target dropbox_id is not a member of the shared folder."
no_explicit_access MemberAccessLevelResult
"The target member only has inherited access to the shared folder."
union JobError
"Error occurred while performing an asynchronous job from :route:`unshare_folder`
or :route:`remove_folder_member`."
unshare_folder_error UnshareFolderError
"Error occurred while performing :route:`unshare_folder` action."
remove_folder_member_error RemoveFolderMemberError
"Error occurred while performing :route:`remove_folder_member` action."
relinquish_folder_membership_error RelinquishFolderMembershipError
"Error occurred while performing :route:`relinquish_folder_membership` action."
route check_job_status(async.PollArg, JobStatus, async.PollError)
"Returns the status of an asynchronous job."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
# --
route unshare_folder(UnshareFolderArg, async.LaunchEmptyResult, UnshareFolderError)
"Allows a shared folder owner to unshare the folder.
You'll need to call :route:`check_job_status` to determine if the action has
completed successfully."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct UnshareFolderArg
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
leave_a_copy Boolean = false
"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."
example default
shared_folder_id = "84528192421"
leave_a_copy = false
union UnshareFolderError
access_error SharedFolderAccessError
team_folder
"This action cannot be performed on a team shared folder."
no_permission
"The current user does not have permission to perform this action."
too_many_files
"This shared folder has too many files to be unshared."
# --
route transfer_folder(TransferFolderArg, Void, TransferFolderError)
"Transfer ownership of a shared folder to a member of the shared folder.
User must have :field:`AccessLevel.owner` access to the shared folder to perform a transfer."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct TransferFolderArg
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
to_dropbox_id DropboxId
"A account or team member ID to transfer ownership to."
example default
shared_folder_id = "84528192421"
to_dropbox_id = "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"
union TransferFolderError
access_error SharedFolderAccessError
invalid_dropbox_id
":field:`TransferFolderArg.to_dropbox_id` is invalid."
new_owner_not_a_member
"The new designated owner is not currently a member of the shared folder."
new_owner_unmounted
"The new designated owner has not added the folder to their Dropbox."
new_owner_email_unverified
"The new designated owner's email address is not verified. This functionality
is only available on accounts with a verified email address. Users can verify
their email address :link:`here https://www.dropbox.com/help/317`."
team_folder
"This action cannot be performed on a team shared folder."
no_permission
"The current user does not have permission to perform this action."
# --
route update_folder_policy(UpdateFolderPolicyArg, SharedFolderMetadata, UpdateFolderPolicyError)
"Update the sharing policies for a shared folder.
User must have :field:`AccessLevel.owner` access to the shared folder to update its policies."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct UpdateFolderPolicyArg
"If any of the policies are unset, then they retain their current setting."
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
member_policy MemberPolicy?
"Who can be a member of this shared folder. Only applicable if the
current user is on a team."
acl_update_policy AclUpdatePolicy?
"Who can add and remove members of this shared folder."
viewer_info_policy ViewerInfoPolicy?
"Who can enable/disable viewer info for this shared folder."
shared_link_policy SharedLinkPolicy?
"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
:field:`SharedLinkPolicy.members`."
link_settings LinkSettings?
"Settings on the link for this folder."
actions List(FolderAction)?
"A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the
response's :field:`SharedFolderMetadata.permissions` field describing the actions the
authenticated user can perform on the folder."
example default
shared_folder_id = "84528192421"
member_policy = team
acl_update_policy = owner
shared_link_policy = members
union UpdateFolderPolicyError
access_error SharedFolderAccessError
not_on_team
":field:`UpdateFolderPolicyArg.member_policy` was set even though user
is not on a team."
team_policy_disallows_member_policy
"Team policy is more restrictive than :field:`ShareFolderArg.member_policy`."
disallowed_shared_link_policy
"The current account is not allowed to select the specified
:field:`ShareFolderArg.shared_link_policy`."
no_permission
"The current user does not have permission to perform this action."
team_folder
"This action cannot be performed on a team shared folder."
# --
route add_folder_member(AddFolderMemberArg, Void, AddFolderMemberError)
"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 :route:`mount_folder` on their behalf."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct AddFolderMemberArg
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
members List(AddMember)
"The intended list of members to add. Added members will receive
invites to join the shared folder."
quiet Boolean = false
"Whether added members should be notified via email and device
notifications of their invite."
custom_message String(min_length=1)?
"Optional message to display to added members in their invitation."
example default
members = [default, account]
shared_folder_id = "84528192421"
custom_message = "Documentation for launch day"
struct AddMember
"The member and type of access the member should have when added to a shared folder."
member MemberSelector
"The member to add to the shared folder."
access_level AccessLevel = viewer
"The access level to grant :field:`member` to the shared folder. :field:`AccessLevel.owner`
is disallowed."
example default
member = default
access_level = editor
example account
member = account
access_level = viewer
union MemberSelector
"Includes different ways to identify a member of a shared folder."
dropbox_id DropboxId
"Dropbox account, team member, or group ID of member."
email common.EmailAddress
"Email address of member."
example default
email = "justin@example.com"
example account
dropbox_id = "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"
example group
dropbox_id = "g:98d36ed08e6290c2e9d536a392f974ee"
union AddFolderMemberError
access_error SharedFolderAccessError
"Unable to access shared folder."
email_unverified
"This user's email address is not verified. This functionality is only
available on accounts with a verified email address. Users can verify
their email address :link:`here https://www.dropbox.com/help/317`."
banned_member
"The current user has been banned."
bad_member AddMemberSelectorError
":field:`AddFolderMemberArg.members` contains a bad invitation recipient."
cant_share_outside_team
"Your team policy does not allow sharing outside of the team."
too_many_members UInt64
"The value is the member limit that was reached."
too_many_pending_invites UInt64
"The value is the pending invite limit that was reached."
rate_limit
"The current user has hit the limit of invites they can send per day. Try again in 24 hours."
too_many_invitees
"The current user is trying to share with too many people at once."
insufficient_plan
"The current user's account doesn't support this action. An example of
this is when adding a read-only member. This action can only be
performed by users that have upgraded to a Pro or Business plan."
team_folder
"This action cannot be performed on a team shared folder."
no_permission
"The current user does not have permission to perform this action."
invalid_shared_folder
"Invalid shared folder error will be returned as an access_error."
example default
no_permission = null
example member
bad_member = default
union AddMemberSelectorError
automatic_group
"Automatically created groups can only be added to team folders."
invalid_dropbox_id DropboxId
"The value is the ID that could not be identified."
invalid_email common.EmailAddress
"The value is the e-email address that is malformed."
unverified_dropbox_id DropboxId
"The value is the ID of the Dropbox user with an unverified email
address. Invite unverified users by email address instead of by their
Dropbox ID."
group_deleted
"At least one of the specified groups in :field:`AddFolderMemberArg.members`
is deleted."
group_not_on_team
"Sharing to a group that is not on the current user's team."
example default
invalid_dropbox_id = "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"
# --
route remove_folder_member(RemoveFolderMemberArg, async.LaunchResultBase, RemoveFolderMemberError)
"Allows an owner or editor (if the ACL update policy allows) of a shared
folder to remove another member."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct RemoveFolderMemberArg
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
member MemberSelector
"The member to remove from the folder."
leave_a_copy Boolean
"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."
example default
shared_folder_id = "84528192421"
member = default
leave_a_copy = false
union RemoveFolderMemberError
access_error SharedFolderAccessError
member_error SharedFolderMemberError
folder_owner
"The target user is the owner of the shared folder. You can't remove
this user until ownership has been transferred to another member."
group_access
"The target user has access to the shared folder via a group."
team_folder
"This action cannot be performed on a team shared folder."
no_permission
"The current user does not have permission to perform this action."
too_many_files
"This shared folder has too many files for leaving a copy. You can
still remove this user without leaving a copy."
union_closed RemoveMemberJobStatus extends async.PollResultBase
complete MemberAccessLevelResult
"Removing the folder member has finished. The value is information about
whether the member has another form of access."
failed RemoveFolderMemberError
example default
complete = default
route check_remove_member_job_status(async.PollArg, RemoveMemberJobStatus, async.PollError)
"Returns the status of an asynchronous job for sharing a folder."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
# --
route update_folder_member(UpdateFolderMemberArg, MemberAccessLevelResult, UpdateFolderMemberError)
"Allows an owner or editor of a shared folder to update another member's
permissions."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct UpdateFolderMemberArg
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
member MemberSelector
"The member of the shared folder to update. Only the
:field:`MemberSelector.dropbox_id` may be set at this time."
access_level AccessLevel
"The new access level for :field:`member`. :field:`AccessLevel.owner`
is disallowed."
example default
shared_folder_id = "84528192421"
member = default
access_level = editor
union UpdateFolderMemberError
access_error SharedFolderAccessError
member_error SharedFolderMemberError
no_explicit_access AddFolderMemberError
"If updating the access type required the member to be added to the shared folder
and there was an error when adding the member."
insufficient_plan
"The current user's account doesn't support this action. An example of
this is when downgrading a member from editor to viewer. This action
can only be performed by users that have upgraded to a Pro or Business
plan."
no_permission
"The current user does not have permission to perform this action."
# --
route mount_folder(MountFolderArg, SharedFolderMetadata, MountFolderError)
"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."
attrs
scope = "sharing.write"
# TODO(kelkabany): Consider exposing mount path as an argument. More error
# cases will be possible.
struct MountFolderArg
shared_folder_id common.SharedFolderId
"The ID of the shared folder to mount."
example default
shared_folder_id = "84528192421"
struct InsufficientQuotaAmounts
space_needed UInt64
"The amount of space needed to add the item (the size of the item)."
space_shortage UInt64
"The amount of extra space needed to add the item."
space_left UInt64
"The amount of space left in the user's Dropbox, less than space_needed."
union MountFolderError
access_error SharedFolderAccessError
inside_shared_folder
"Mounting would cause a shared folder to be inside another, which is
disallowed."
insufficient_quota InsufficientQuotaAmounts
"The current user does not have enough space to mount the shared
folder."
already_mounted
"The shared folder is already mounted."
no_permission
"The current user does not have permission to perform this action."
not_mountable
"The shared folder is not mountable. One example where this can occur
is when the shared folder belongs within a team folder in the user's
Dropbox."
# --
route unmount_folder(UnmountFolderArg, Void, UnmountFolderError)
"The current user unmounts the designated folder. They can re-mount the
folder at a later time using :route:`mount_folder`."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct UnmountFolderArg
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
example default
shared_folder_id = "84528192421"
union UnmountFolderError
access_error SharedFolderAccessError
no_permission
"The current user does not have permission to perform this action."
not_unmountable
"The shared folder can't be unmounted. One example where this can occur
is when the shared folder's parent folder is also a shared folder that
resides in the current user's Dropbox."
# --
route relinquish_folder_membership(RelinquishFolderMembershipArg, async.LaunchEmptyResult, RelinquishFolderMembershipError)
"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."
attrs
scope = "sharing.write"
struct RelinquishFolderMembershipArg
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
leave_a_copy Boolean = false
"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."
example default
shared_folder_id = "84528192421"
leave_a_copy = false
union RelinquishFolderMembershipError
access_error SharedFolderAccessError
folder_owner
"The current user is the owner of the shared folder. Owners cannot relinquish membership to
their own folders. Try unsharing or transferring ownership first."
mounted
"The shared folder is currently mounted. Unmount the shared folder before relinquishing
membership."
group_access
"The current user has access to the shared folder via a group. You can't relinquish
membership to folders shared via groups."
team_folder
"This action cannot be performed on a team shared folder."
no_permission
"The current user does not have permission to perform this action."
no_explicit_access
"The current user only has inherited access to the shared folder. You can't relinquish
inherited membership to folders."
# --
route set_access_inheritance (SetAccessInheritanceArg, ShareFolderLaunch, SetAccessInheritanceError)
"Change the inheritance policy of an existing Shared Folder. Only permitted for shared folders in a shared team root.
If a :field:`ShareFolderLaunch.async_job_id` is returned, you'll need to
call :route:`check_share_job_status` until the action completes to get the
metadata for the folder."
attrs
scope = "sharing.write"
struct SetAccessInheritanceArg
access_inheritance AccessInheritance = inherit
"The access inheritance settings for the folder."
shared_folder_id common.SharedFolderId
"The ID for the shared folder."
example default
access_inheritance = inherit
shared_folder_id = "84528192421"
union SetAccessInheritanceError
access_error SharedFolderAccessError
"Unable to access shared folder."
no_permission
"The current user does not have permission to perform this action."
example default
no_permission = null