namespace sharing
import common
import files
import users
import seen_state
alias PathOrId = String(pattern="((\/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?", min_length=1)
###########################################
# Generic route error related definitions #
###########################################
union SharingUserError
"User account had a problem preventing this action."
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`."
union SharingFileAccessError
"User could not access this file."
no_permission
"Current user does not have sufficient privileges to perform the desired action."
invalid_file
"File specified was not found."
is_folder
"A folder can't be shared this way. Use folder sharing or a shared link instead."
inside_public_folder
"A file inside a public folder can't be shared this way. Use a public link instead."
inside_osx_package
"A Mac OS X package can't be shared this way. Use a shared link instead."
union FileErrorResult
file_not_found_error files.Id
"File specified by id was not found."
invalid_file_action_error files.Id
"User does not have permission to take the specified action on the file."
permission_denied_error files.Id
"User does not have permission to access file specified by file.Id."
#############################################
# File metadata and permissions definitions #
#############################################
union FileAction
"Sharing actions that may be taken on files."
disable_viewer_info
"Disable viewer information on the file."
edit_contents
"Change or edit contents of the file."
enable_viewer_info
"Enable viewer information on the file."
invite_viewer
"Add a member with view permissions."
invite_viewer_no_comment
"Add a member with view permissions but no comment permissions."
invite_editor
"Add a member with edit permissions."
unshare
"Stop sharing this file."
relinquish_membership
"Relinquish one's own membership to the file."
share_link
"Use create_view_link and create_edit_link instead."
create_link
"Use create_view_link and create_edit_link instead."
create_view_link
"Create a shared link to a file that only allows users to view the content."
create_edit_link
"Create a shared link to a file that allows users to edit the content."
example default
edit_contents = null
struct FilePermission
"Whether the user is allowed to take the sharing action on the file."
action FileAction
"The action that the user may wish to take on the file."
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 = edit_contents
allow = false
reason = user_not_same_team_as_owner
struct SharedFileMetadata
"Properties of the shared file."
access_type AccessLevel?
"The current user's access level for this shared file."
id files.FileId
"The ID of the file."
expected_link_metadata ExpectedSharedContentLinkMetadata?
"The expected metadata of the link associated for the file when it is first shared.
Absent if the link already exists. This is for an unreleased feature so it may not be
returned yet."
link_metadata SharedContentLinkMetadata?
"The metadata of the link associated for the file. This is for an unreleased feature so
it may not be returned yet."
name String
"The name of this file."
owner_display_names List(String)?
"The display names of the users that own the file. If the file 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 file. This field is not present if the file
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
file is contained within a shared folder."
path_display String?
"The cased path to be used for display purposes only. In rare instances
the casing will not correctly match the user's filesystem, but this
behavior will match the path provided in the Core API v1.
Absent for unmounted files."
path_lower String?
"The lower-case full path of this file. Absent for unmounted files."
permissions List(FilePermission)?
"The sharing permissions that requesting user has on this file. This
corresponds to the entries given in :field:`GetFileMetadataBatchArg.actions`
or :field:`GetFileMetadataArg.actions`."
policy FolderPolicy
"Policies governing this shared file."
preview_url String
"URL for displaying a web preview of the shared file."
time_invited common.DropboxTimestamp?
"Timestamp indicating when the current user was invited to this shared file. If the user was
not invited to the shared file, the timestamp will indicate when the user was invited to the
parent shared folder. This value may be absent."
example default
policy = default
permissions = []
owner_display_names = ["Jane Doe"]
owner_team = default
preview_url = "https://www.dropbox.com/scl/fi/fir9vjelf"
path_lower = "/dir/file.txt"
path_display = "/dir/file.txt"
name = "file.txt"
id = "id:3kmLmQFnf1AAAAAAAAAAAw"
time_invited = "2016-01-20T00:00:00Z"
access_type = viewer
union ViewerInfoPolicy
enabled
"Viewer information is available on this file."
disabled
"Viewer information is disabled on this file."
##################################
# File membership mutation types #
##################################
struct FileMemberActionResult
"Per-member result for :route:`add_file_member`."
member MemberSelector
"One of specified input members."
result FileMemberActionIndividualResult
"The outcome of the action on this member."
sckey_sha1 String?
"The SHA-1 encrypted shared content key."
invitation_signature List(String)?
"The sharing sender-recipient invitation signatures for the input member_id.
A member_id can be a group and thus have multiple users and multiple invitation signatures."
example default
member = default
result = default
sckey_sha1 = "32gggb672f987b2d94ef1741616bdf37d565e8c1"
invitation_signature = ["32gggb672f987b2d94ef1741616bdf37d565e8c1:c1ce0a9ef6ggg65e6e2f43514082ea5ffefd9cf5"]
union_closed FileMemberActionIndividualResult
success AccessLevel?
"Part of the response for both add_file_member and remove_file_member_v1 (deprecated).
For add_file_member, indicates giving access was successful and at what AccessLevel.
For remove_file_member_v1, indicates member was successfully removed from the file. If AccessLevel is given,
the member still has access via a parent shared folder."
member_error FileMemberActionError
"User was not able to perform this action."
example default
success = null
union FileMemberRemoveActionResult
success MemberAccessLevelResult
"Member was successfully removed from this file."
member_error FileMemberActionError
"User was not able to remove this member."
union AddFileMemberError
"Errors for :route:`add_file_member`."
user_error SharingUserError
access_error SharingFileAccessError
rate_limit
"The user has reached the rate limit for invitations."
invalid_comment
"The custom message did not pass comment permissions checks."
union RemoveFileMemberError
"Errors for :route:`remove_file_member_2`."
user_error SharingUserError
access_error SharingFileAccessError
no_explicit_access MemberAccessLevelResult
"This member does not have explicit access to the file and therefore cannot be removed.
The return value is the access that a user might have to the file from a parent folder."
union FileMemberActionError
invalid_member
"Specified member was not found."
no_permission
"User does not have permission to perform this action on this member."
access_error SharingFileAccessError
"Specified file was invalid or user does not have access."
no_explicit_access MemberAccessLevelResult
"The action cannot be completed because the target member does not have explicit access
to the file. The return value is the access that the member has to the file from a parent folder."
#####################
# Route Definitions #
#####################
route add_file_member(AddFileMemberArgs, List(FileMemberActionResult), AddFileMemberError)
"Adds specified members to a file."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct AddFileMemberArgs
"Arguments for :route:`add_file_member`."
file PathOrId
"File to which to add members."
members List(MemberSelector)
"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."
custom_message String?
"Message to send to added members in their invitation."
quiet Boolean = false
"Whether added members should be notified via email and device notifications of
their invitation."
access_level AccessLevel = viewer
"AccessLevel union object, describing what access level we want to give new members."
add_message_as_comment Boolean = false
"If the custom message should be added as a comment on the file."
example default
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
members = [default]
custom_message = "This is a custom message about ACME.doc"
quiet = false
access_level = viewer
# --
struct UpdateFileMemberArgs
"Arguments for :route:`update_file_member`."
file PathOrId
"File for which we are changing a member's access."
member MemberSelector
"The member whose access we are changing."
access_level AccessLevel
"The new access level for the member."
example default
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
member = default
access_level = viewer
route update_file_member(UpdateFileMemberArgs, MemberAccessLevelResult, FileMemberActionError)
"Changes a member's access on a shared file."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
# --
route get_file_metadata(GetFileMetadataArg, SharedFileMetadata, GetFileMetadataError)
"Returns shared file metadata."
attrs
select_admin_mode = "team_admin"
scope = "sharing.read"
struct GetFileMetadataArg
"Arguments of :route:`get_file_metadata`."
file PathOrId
"The file to query."
actions List(FileAction)?
"A list of `FileAction`s corresponding to `FilePermission`s that should appear in the
response's :field:`SharedFileMetadata.permissions` field describing the actions the
authenticated user can perform on the file."
example default
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
actions = []
union GetFileMetadataError
"Error result for :route:`get_file_metadata`."
user_error SharingUserError
access_error SharingFileAccessError
# --
route get_file_metadata/batch(GetFileMetadataBatchArg, List(GetFileMetadataBatchResult), SharingUserError)
"Returns shared file metadata."
attrs
scope = "sharing.read"
struct GetFileMetadataBatchArg
"Arguments of :route:`get_file_metadata/batch`."
files List(PathOrId, max_items=100)
"The files to query."
actions List(FileAction)?
"A list of `FileAction`s corresponding to `FilePermission`s that should appear in the
response's :field:`SharedFileMetadata.permissions` field describing the actions the
authenticated user can perform on the file."
example default
files = ["id:3kmLmQFnf1AAAAAAAAAAAw","id:VvTaJu2VZzAAAAAAAAAADQ"]
actions = []
struct GetFileMetadataBatchResult
"Per file results of :route:`get_file_metadata/batch`."
file PathOrId
"This is the input file identifier corresponding to one of
:field:`GetFileMetadataBatchArg.files`."
result GetFileMetadataIndividualResult
"The result for this particular file."
example default
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
result = default
example file_error
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
result = file_error
union GetFileMetadataIndividualResult
metadata SharedFileMetadata
"The result for this file if it was successful."
access_error SharingFileAccessError
"The result for this file if it was an error."
example default
metadata = default
example file_error
access_error = invalid_file
# --
route list_file_members(ListFileMembersArg, SharedFileMembers, ListFileMembersError)
"Use to obtain the members who have been invited to a file, both inherited
and uninherited members."
attrs
select_admin_mode = "team_admin"
scope = "sharing.read"
struct ListFileMembersArg
"Arguments for :route:`list_file_members`."
file PathOrId
"The file for which you want to see members."
actions List(MemberAction)?
"The actions for which to return permissions on a member."
include_inherited Boolean = true
"Whether to include members who only have access from a parent shared folder."
limit UInt32(min_value=1, max_value=300) = 100
"Number of members to return max per query. Defaults to 100 if no limit is specified."
example default
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
struct SharedFileMembers
"Shared file user, group, and invitee membership.
Used for the results of :route:`list_file_members` and
:route:`list_file_members/continue`, and used as part of the results
for :route:`list_file_members/batch`."
users List(UserFileMembershipInfo)
"The list of user members of the shared file."
groups List(GroupMembershipInfo)
"The list of group members of the shared file."
invitees List(InviteeMembershipInfo)
"The list of invited members of a file, but have not logged in and
claimed this."
cursor String?
"Present if there are additional shared file members that have not been returned yet. Pass
the cursor into :route:`list_file_members/continue` to list additional members."
example default
users = [default]
groups = [default]
invitees = [default]
union ListFileMembersError
"Error for :route:`list_file_members`."
user_error SharingUserError
access_error SharingFileAccessError
struct UserFileMembershipInfo extends UserMembershipInfo
"The information about a user member of the shared content with an appended last seen timestamp."
time_last_seen common.DropboxTimestamp?
"The UTC timestamp of when the user has last seen the content. Only populated if the
user has seen the content and the caller has a plan that includes viewer history."
platform_type seen_state.PlatformType?
"The platform on which the user has last seen the content, or unknown."
example default
user = default
access_type = owner
permissions = []
time_last_seen = "2016-01-20T00:00:00Z"
platform_type = unknown
# --
route list_file_members/batch(ListFileMembersBatchArg, List(ListFileMembersBatchResult), SharingUserError)
"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."
attrs
scope = "sharing.read"
struct ListFileMembersBatchArg
"Arguments for :route:`list_file_members/batch`."
files List(PathOrId, max_items=100)
"Files for which to return members."
limit UInt32(max_value=20) = 10
"Number of members to return max per query. Defaults to 10 if no limit is specified."
example default
files = ["id:3kmLmQFnf1AAAAAAAAAAAw","id:VvTaJu2VZzAAAAAAAAAADQ"]
limit = 10
struct ListFileMembersBatchResult
"Per-file result for :route:`list_file_members/batch`."
file PathOrId
"This is the input file identifier, whether an ID or a path."
result ListFileMembersIndividualResult
"The result for this particular file."
example default
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
result = default
example member_error
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
result = file_error
struct ListFileMembersCountResult
members SharedFileMembers
"A list of members on this file."
member_count UInt32
"The number of members on this file. This does not include inherited members."
example default
members = default
member_count = 3
union ListFileMembersIndividualResult
result ListFileMembersCountResult
"The results of the query for this file if it was successful."
access_error SharingFileAccessError
"The result of the query for this file if it was an error."
example default
result = default
example file_error
access_error = invalid_file
# --
route list_file_members/continue(ListFileMembersContinueArg, SharedFileMembers, ListFileMembersContinueError)
"Once a cursor has been retrieved from :route:`list_file_members` or
:route:`list_file_members/batch`, use this to paginate through all shared
file members."
attrs
scope = "sharing.read"
struct ListFileMembersContinueArg
"Arguments for :route:`list_file_members/continue`."
cursor String
"The cursor returned by your last call to :route:`list_file_members`,
:route:`list_file_members/continue`, or :route:`list_file_members/batch`."
example default
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
union ListFileMembersContinueError
"Error for :route:`list_file_members/continue`."
user_error SharingUserError
access_error SharingFileAccessError
invalid_cursor
":field:`ListFileMembersContinueArg.cursor` is invalid."
# --
route list_received_files(ListFilesArg, ListFilesResult, SharingUserError)
"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."
attrs
select_admin_mode = "team_admin"
scope = "sharing.read"
struct ListFilesArg
"Arguments for :route:`list_received_files`."
limit UInt32(min_value=1, max_value=300) = 100
"Number of files to return max per query. Defaults to 100 if no limit
is specified."
actions List(FileAction)?
"A list of `FileAction`s corresponding to `FilePermission`s that should appear in the
response's :field:`SharedFileMetadata.permissions` field describing the actions the
authenticated user can perform on the file."
example default
limit = 100
actions = []
struct ListFilesResult
"Success results for :route:`list_received_files`."
entries List(SharedFileMetadata)
"Information about the files shared with current user."
cursor String?
"Cursor used to obtain additional shared files."
example default
entries = [default]
cursor = "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9cmV2aXNpb24H3Qf6o1fkHxQ"
# --
route list_received_files/continue (ListFilesContinueArg, ListFilesResult, ListFilesContinueError)
"Get more results with a cursor from :route:`list_received_files`."
attrs
scope = "sharing.read"
struct ListFilesContinueArg
"Arguments for :route:`list_received_files/continue`."
cursor String
"Cursor in :field:`ListFilesResult.cursor`."
example default
cursor = "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9emfGRlc2MCRWxpbWl0BGRId"
union ListFilesContinueError
"Error results for :route:`list_received_files/continue`."
user_error SharingUserError
"User account had a problem."
invalid_cursor
":field:`ListFilesContinueArg.cursor` is invalid."
# --
route remove_file_member(RemoveFileMemberArg, FileMemberActionIndividualResult, RemoveFileMemberError) deprecated by remove_file_member_2
"Identical to remove_file_member_2 but with less information returned."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
route remove_file_member_2(RemoveFileMemberArg, FileMemberRemoveActionResult, RemoveFileMemberError)
"Removes a specified member from the file."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct RemoveFileMemberArg
"Arguments for :route:`remove_file_member_2`."
file PathOrId
"File from which to remove members."
member 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."
example default
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
member = default
# --
route relinquish_file_membership(RelinquishFileMembershipArg, Void, RelinquishFileMembershipError)
"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."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct RelinquishFileMembershipArg
file PathOrId
"The path or id for the file."
example default
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
union RelinquishFileMembershipError
access_error SharingFileAccessError
group_access
"The current user has access to the shared file via a group. You can't relinquish
membership to a file shared via groups."
no_permission
"The current user does not have permission to perform this action."
# --
route unshare_file(UnshareFileArg, Void, UnshareFileError)
"Remove all members from this file. Does not remove inherited members."
attrs
select_admin_mode = "team_admin"
scope = "sharing.write"
struct UnshareFileArg
"Arguments for :route:`unshare_file`."
file PathOrId
"The file to unshare."
example default
file = "id:3kmLmQFnf1AAAAAAAAAAAw"
union UnshareFileError
"Error result for :route:`unshare_file`."
user_error SharingUserError
access_error SharingFileAccessError
example default
user_error = email_unverified