sharing.stone

namespace sharing
    "This namespace contains endpoints and data types for creating and managing shared links and
    shared folders."

import account_id
import async
import common
import files
import seen_state
import team_common
import team_policies
import users
import users_common

route get_file_metadata (GetFileMetadataArg, SharedFileMetadata, GetFileMetadataError)
    "Returns shared file metadata."

    attrs
        auth = "user"
        scope = "sharing.read"
        select_admin_mode = "team_admin"


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
        auth = "user"
        scope = "sharing.read"
        select_admin_mode = "whole_team"


route list_shared_links (ListSharedLinksArg, ListSharedLinksResult, ListSharedLinksError)
    "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.
    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."

    attrs
        allow_app_folder_app = true
        auth = "user"
        scope = "sharing.read"
        select_admin_mode = "whole_team"


union LinkExpiry
    remove_expiry
        "Remove the currently set expiry for the link."
    set_expiry common.DropboxTimestamp
        "Set a new expiry or change an existing expiry."

union LinkPassword
    remove_password
        "Remove the currently set password for the link."
    set_password String
        "Set a new password or change an existing password."

union LinkAudience
    public
        "Link is accessible by anyone."
    team
        "Link is accessible only by team members."
    no_one
        "The link can be used by no one. The link merely points the user to the content, and does
        not grant additional rights to the user. Members of the content who use this link can only
        access the content with their pre-existing access rights."
    password
        @common.Deprecated
        "Use `require_password` instead. A link-specific password is required to access the
        link. Login is not required."
    members
        @common.Deprecated
        "Link is accessible only by members of the content."

union LinkAction
    "Actions that can be performed on a link."
    change_access_level
        "Change the access level of the link."
    change_audience
        "Change the audience of the link."
    remove_expiry
        "Remove the expiry date of the link."
    remove_password
        "Remove the password of the link."
    set_expiry
        "Create or modify the expiry date of the link."
    set_password
        "Create or modify the password of the link."

struct LinkSettings
    "Settings that apply to a link."
    access_level AccessLevel?
        "The access level on the link for this file. Currently,
        it only accepts 'viewer' and 'viewer_no_comment'."
    audience LinkAudience?
        "The type of audience on the link for this file."
    expiry LinkExpiry?
        "An expiry timestamp to set on a link."
    password LinkPassword?
        "The password for the link."

struct LinkPermission
    "Permissions for actions that can be performed on a link."
    action LinkAction
    allow Boolean
    reason PermissionDeniedReason?

    example default
        action = change_audience
        allow = true

struct SharedContentLinkMetadataBase
    access_level AccessLevel?
        "The access level on the link for this file."
    audience_options List(LinkAudience)
        "The audience options that are available for the content. Some audience options may be
        unavailable. For example, team_only may be unavailable if the content is not owned by a
        user on a team. The 'default' audience option is always available if the user can modify
        link settings."
    audience_restricting_shared_folder AudienceRestrictingSharedFolder?
        "The shared folder that prevents the link audience for this link from being more
        restrictive."
    current_audience LinkAudience
        "The current audience of the link."
    expiry common.DropboxTimestamp?
        "Whether the link has an expiry set on it. A link with an expiry will have its
        audience changed to members when the expiry is reached."
    link_permissions List(LinkPermission)
        "A list of permissions for actions you can perform on the link."
    password_protected Boolean
        "Whether the link is protected by a password."

struct SharedContentLinkMetadata extends SharedContentLinkMetadataBase
    "Metadata of a shared link for a file or folder."
    audience_exceptions AudienceExceptions?
        "The content inside this folder with link audience different than this folder's. This is
        only returned when an endpoint that returns metadata for a single shared folder is called,
        e.g. /get_folder_metadata."
    url String
        "The URL of the link."

    example default
        audience_options = [public, team, members]
        current_audience = public
        link_permissions = [default]
        password_protected = false
        url = ""

struct ExpectedSharedContentLinkMetadata extends SharedContentLinkMetadataBase
    "The expected metadata of a shared link for a file or folder when a link is first created for
    the content. Absent if the link already exists."

    example default
        audience_options = [public, team, members]
        current_audience = public
        link_permissions = [default]
        password_protected = false

struct AudienceRestrictingSharedFolder
    "Information about the shared folder that prevents the link audience for this link from being
    more restrictive."
    shared_folder_id common.SharedFolderId
        "The ID of the shared folder."
    name String
        "The name of the shared folder."
    audience LinkAudience
        "The link audience of the shared folder."

struct AudienceExceptions
    "The total count and truncated list of information of content inside this folder that has a
    different audience than the link on this folder. This is only returned for folders."
    count UInt32
    exceptions List(AudienceExceptionContentInfo)
        "A truncated list of some of the content that is an exception. The length of this list could
        be smaller than the count since it is only a sample but will not be empty as long as
        count is not 0."

    example default
        count = 0
        exceptions = []

struct AudienceExceptionContentInfo
    "Information about the content that has a link audience different than that of this folder."
    name String
        "The name of the content, which is either a file or a folder."

    example default
        name = "sample file name"


route get_shared_link_file (GetSharedLinkFileArg, SharedLinkMetadata, GetSharedLinkFileError)
    "Download the shared link's file from a user's Dropbox.
    This is a download-style endpoint that returns the file content."

    attrs
        allow_app_folder_app = true
        auth = "app, user"
        host = "content"
        scope = "sharing.read"
        style = "download"


route create_shared_link_with_settings (CreateSharedLinkWithSettingsArg, SharedLinkMetadata, CreateSharedLinkWithSettingsError)
    "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)."

    attrs
        allow_app_folder_app = true
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route get_shared_link_metadata (GetSharedLinkMetadataArg, SharedLinkMetadata, SharedLinkMetadataError)
    "Get the shared link's metadata."

    attrs
        allow_app_folder_app = true
        auth = "app, user"
        scope = "sharing.read"

route modify_shared_link_settings (ModifySharedLinkSettingsArgs, SharedLinkMetadata, ModifySharedLinkSettingsError)
    "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 SharedLinkMetadata will
    reflect the actual visibility of the shared link and the
    LinkPermissions.requested_visibility will reflect the requested visibility."

    attrs
        allow_app_folder_app = true
        auth = "user"
        scope = "sharing.write"


route create_shared_link (CreateSharedLinkArg, PathLinkMetadata, CreateSharedLinkError) deprecated
    "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 revoke_shared_link.
    DEPRECATED: Use create_shared_link_with_settings instead."

    attrs
        allow_app_folder_app = true
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route get_shared_links (GetSharedLinksArg, GetSharedLinksResult, GetSharedLinksError) deprecated
    "DEPRECATED: Use list_shared_links instead. This endpoint will be retired in October 2026.
    Returns a list of :type:`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."

    attrs
        allow_app_folder_app = true
        auth = "user"
        scope = "sharing.read"

route revoke_shared_link (RevokeSharedLinkArg, Void, RevokeSharedLinkError)
    "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 list_shared_links with the file as the
    ListSharedLinksArg.path argument."

    attrs
        allow_app_folder_app = true
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"


alias GetSharedLinkFileArg = GetSharedLinkMetadataArg

alias Id = files.Id

alias Path = files.Path

alias ReadPath = files.ReadPath

alias Rev = files.Rev

alias TeamInfo = users.Team

union AlphaResolvedVisibility extends ResolvedVisibility
    "check documentation for ResolvedVisibility."

union CreateSharedLinkError
    path files.LookupError

union_closed CreateSharedLinkWithSettingsError
    path files.LookupError
    email_not_verified
        "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`."
    shared_link_already_exists SharedLinkAlreadyExistsMetadata?
        "The shared link already exists. You can call :route:`list_shared_links` to get the
        existing link, or use the provided metadata if it is returned.
        Existing link metadata will not be returned if custom settings were specified in the request that could make the existing link incompatible with the requested settings."
    settings_error SharedLinkSettingsError
        "There is an error with the given settings."
    access_denied
        "The user is not allowed to create a shared link to the specified file. For
        example, this can occur if the file is restricted or if the user's links are
        :link:`banned https://help.dropbox.com/files-folders/share/banned-links`."
    banned_member
        "The current user has been :link:`banned https://help.dropbox.com/files-folders/share/banned-links` for abuse reasons."
    too_many_shared_folders
        "Your Dropbox folder will have too many shared folders after the operation.
        https://help.dropbox.com/share/shared-folder-faq#Is-there-a-limit-to-the-number-of-shared-folders-I-can-create"

union GetSharedLinkFileError extends SharedLinkError
    shared_link_is_directory
        "Directories cannot be retrieved by this endpoint."

union GetSharedLinksError
    path files.MalformedPathError

union LinkAccessLevel
    viewer
        "Users who use the link can view and comment on the content."
    editor
        "Users who use the link can edit, view and comment on the content."

union LinkAudienceDisallowedReason extends VisibilityPolicyDisallowedReason
    "check documentation for VisibilityPolicyDisallowedReason."

union ListSharedLinksError
    path files.LookupError
    reset
        "Indicates that the cursor has been invalidated. Call
        :route:`list_shared_links` to obtain a new cursor."

union ModifySharedLinkSettingsError extends SharedLinkError
    settings_error SharedLinkSettingsError
        "There is an error with the given settings."
    email_not_verified
        "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_closed PendingUploadMode
    "Flag to indicate pending upload default (for linking to not-yet-existing paths)."
    file
        "Assume pending uploads are files."
    folder
        "Assume pending uploads are folders."

union RequestedLinkAccessLevel
    viewer
        "Users who use the link can view and comment on the content."
    editor
        "Users who use the link can edit, view and comment on the content.
        Note not all file types support edit links yet."
    max
        "Request for the maximum access level you can set the link to."
    default
        "Request for the default access level the user has set."

union_closed RequestedVisibility
    "The access permission that can be requested by the caller for the shared link.
    Note that the final resolved visibility of the shared link takes into account other aspects,
    such as team and shared folder settings.
    Check the :type:`ResolvedVisibility` for more info on the possible resolved visibility values
    of shared links."
    public
        "Anyone who has received the link can access it. No login required."
    team_only
        "Only members of the same team can
        access the link. Login is required."
    password
        "A link-specific password is required to access the
        link. Login is not required."

union ResolvedVisibility extends RequestedVisibility
    "The actual access permissions values of shared links after taking into account user
    preferences and the team and shared folder settings.
    Check the :type:`RequestedVisibility` for more info on the possible visibility values
    that can be set by the shared link's owner."
    team_and_password
        "Only members of the same team who
        have the link-specific password can access the link. Login is required."
    shared_folder_only
        "Only members of the shared folder containing the linked file
        can access the link. Login is required."
    no_one
        "The link merely points the user to the content, and does not grant any additional rights.
        Existing members of the content who use this link can only access the content with their
        pre-existing access rights. Either on the file directly, or inherited from a parent folder."
    only_you
        "Only the current user can view this link."

union RevokeSharedLinkError extends SharedLinkError
    shared_link_malformed
        "Shared link is malformed."

union SharedLinkAccessFailureReason
    login_required
        "User is not logged in."
    email_verify_required
        "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`."
    password_required
        "The link is password protected."
    team_only
        "Access is allowed for team members only."
    owner_only
        "Access is allowed for the shared link's owner only."

union SharedLinkAlreadyExistsMetadata
    metadata SharedLinkMetadata
        "Metadata of the shared link that already exists."

union SharedLinkError
    shared_link_not_found
        "The shared link wasn't found."
    shared_link_access_denied
        "The caller is not allowed to access this shared link."
    unsupported_link_type
        "This type of link is not supported; use :route:`files.export` instead."
    unsupported_parameter_field
        "Private shared links do not support `path` or `link_password` parameter fields."

union SharedLinkMetadataError extends SharedLinkError
    "The potential errors for a call to get_shared_link_metadata."

union_closed SharedLinkSettingsError
    invalid_settings
        "The given settings are invalid
        (for example, all attributes of the :type:`SharedLinkSettings` are empty,
        the requested visibility is :field:`RequestedVisibility.password` but the
        :field:`SharedLinkSettings.link_password` is missing, :field:`SharedLinkSettings.expires`
        is set to the past, etc.)."
    not_authorized
        "User is not allowed to modify the settings of this link. Note that basic
        users can only set :field:`RequestedVisibility.public`
        as the :field:`SharedLinkSettings.requested_visibility` and cannot
        set :field:`SharedLinkSettings.expires`."

union Visibility
    "Who can access a shared link.
    The most open visibility is :field:`public`.
    The default depends on many aspects, such as team and user
    preferences and shared folder settings."
    public
        "Anyone who has received the link can access it. No login required."
    team_only
        "Only members of the same team can
        access the link. Login is required."
    password
        "A link-specific password is required to access the
        link. Login is not required."
    team_and_password
        "Only members of the same team who
        have the link-specific password can access the link."
    shared_folder_only
        "Only members of the shared folder containing the linked file
        can access the link. Login is required."

union VisibilityPolicyDisallowedReason
    delete_and_recreate
        "The user needs to delete and recreate the link to change the visibility policy."
    restricted_by_shared_folder
        "The parent shared folder restricts sharing of links outside the shared folder. To change
        the visibility policy, remove the restriction from the parent shared folder."
    restricted_by_team
        "The team policy prevents links being shared outside the team."
    user_not_on_team
        "The user needs to be on a team to set this policy."
    user_account_type
        "The user is a basic user or is on a limited team."
    permission_denied
        "The user does not have permission."

union ChangeLinkExpirationPolicy
    "Enumerates acceptable values for team's ChangeLinkExpirationPolicy setting."
    allowed
    not_allowed

struct LinkMetadata
    "Metadata for a shared link. This can be either a
    :type:`PathLinkMetadata` or :type:`CollectionLinkMetadata`."
    union
        path PathLinkMetadata
        collection CollectionLinkMetadata
    url String
        "URL of the shared link."
    visibility Visibility
        "Who can access the link."
    expires common.DropboxTimestamp?
        "Expiration time, if set. By default the link won't expire."

    example default
        path = default

struct SharedLinkMetadata
    "The metadata of a shared link."
    union
        file FileLinkMetadata
        folder FolderLinkMetadata
    url String
        "URL of the shared link."
    id Id?
        "A unique identifier for the linked file."
    name String
        "The linked file name (including extension).
        This never contains a slash."
    expires common.DropboxTimestamp?
        "Expiration time, if set. By default the link won't expire."
    path_lower String?
        "The lowercased full path in the user's Dropbox. This always starts with a slash.
        This field will only be present only if the linked file is in the authenticated user's
        dropbox and the user is the owner of the link."
    link_permissions LinkPermissions
        "The link's access permissions."
    team_member_info TeamMemberInfo?
        "The team membership information of the link's owner.  This field will only be present
        if the link's owner is a team member."
    content_owner_team_info TeamInfo?
        "The team information of the content's owner. This field will only be present if
        the content's owner is a team member and the content's owner team is different from the
        link's owner team."

    example default
        file = default

    example folder_link_metadata
        folder = default

struct CollectionLinkMetadata extends LinkMetadata
    "Metadata for a collection-based shared link."

    example default
        url = "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
        expires = null
        visibility = public

struct CreateSharedLinkArg
    path String
        "The path to share."
    short_url Boolean = false
        @common.Deprecated
    pending_upload PendingUploadMode?
        "If it's okay to share a path that does not yet exist, set this to
        either :field:`PendingUploadMode.file` or :field:`PendingUploadMode.folder`
        to indicate whether to assume it's a file or folder."

    example default
        path = "/Homework/Math/Prime_Numbers.txt"

struct CreateSharedLinkWithSettingsArg
    path ReadPath
        "The path to be shared by the shared link."
    settings SharedLinkSettings?
        "The requested settings for the newly created shared link."

    example default
        path = "/Prime_Numbers.txt"
        settings = default

struct FileLinkMetadata extends SharedLinkMetadata
    "The metadata of a file shared link."
    client_modified common.DropboxTimestamp
        "The modification time set by the desktop client
        when the file was added to Dropbox. Since this time is not verified
        (the Dropbox server stores whatever the desktop client sends up), this
        should only be used for display purposes (such as sorting) and not,
        for example, to determine if a file has changed or not."
    server_modified common.DropboxTimestamp
        "The last time the file was modified on Dropbox."
    rev Rev
        "A unique identifier for the current revision of a file. This field is
        the same rev as elsewhere in the API and can be used to detect changes
        and avoid conflicts."
    size UInt64
        "The file size in bytes."

    example default
        url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
        id = "id:a4ayc_80_OEAAAAAAAAAXw"
        name = "Prime_Numbers.txt"
        path_lower = "/homework/math/prime_numbers.txt"
        link_permissions = default
        team_member_info = default
        client_modified = "2015-05-12T15:50:38Z"
        server_modified = "2015-05-12T15:50:38Z"
        rev = "a1c10ce0dd78"
        size = 7212

struct FolderLinkMetadata extends SharedLinkMetadata
    "The metadata of a folder shared link."

    example default
        url = "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
        id = "id:a4ayc_80_OEAAAAAAAAAXw"
        name = "Math"
        path_lower = "/homework/math"
        team_member_info = default
        link_permissions = default

struct GetSharedLinkMetadataArg
    url String
        "URL of the shared link."
    path Path?
        "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 String?
        "If the shared link has a password, this parameter can be used."

    example default
        url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
        path = "/Prime_Numbers.txt"

struct GetSharedLinksArg
    path String?
        "See :route:`get_shared_links` description."

    example default
        path = ""

    example math_homework_links
        path = "/Homework/Math"

struct GetSharedLinksResult
    links List(LinkMetadata)
        "Shared links applicable to the path argument."

    example default
        links = [default]

struct LinkAudienceOption
    audience LinkAudience
        "Specifies who can access the link."
    allowed Boolean
        "Whether the user calling this API can select this audience option."
    disallowed_reason LinkAudienceDisallowedReason?
        "If :field:`allowed` is :val:`false`, this will provide the reason that the user is not
        permitted to set the visibility to this policy."

    example public
        audience = public
        allowed = true

    example team
        audience = team
        allowed = false

    example no_one
        audience = no_one
        allowed = true

struct LinkPermissions
    resolved_visibility ResolvedVisibility?
        "The current visibility of the link after considering the shared links policies of the
        the team (in case the link's owner is part of a team) and the shared folder (in case the
        linked file is part of a shared folder). This field is shown only if the caller has access
        to this info (the link's owner always has access to this data). For some links, an
        effective_audience value is returned instead."
    requested_visibility RequestedVisibility?
        "The shared link's requested visibility. This can be overridden by the team and shared
        folder policies. The final visibility, after considering these policies, can be found in
        :field:`resolved_visibility`. This is shown only if the caller is the link's
        owner and resolved_visibility is returned instead of effective_audience."
    can_revoke Boolean
        "Whether the caller can revoke the shared link."
    revoke_failure_reason SharedLinkAccessFailureReason?
        "The failure reason for revoking the link. This field will only be present if the
        :field:`can_revoke` is :val:`false`."
    effective_audience LinkAudience?
        "The type of audience who can benefit from the access level specified by the
        `link_access_level` field."
    link_access_level LinkAccessLevel?
        "The access level that the link will grant to its users. A link can grant additional rights
        to a user beyond their current access level. For example, if a user was invited as a viewer
        to a file, and then opens a link with `link_access_level` set to `editor`, then they will
        gain editor privileges. The `link_access_level` is a property of the link, and does not
        depend on who is calling this API. In particular, `link_access_level` does not take into
        account the API caller's current permissions to the content."
    visibility_policies List(VisibilityPolicy)
        "A list of policies that the user might be able to set for the visibility."
    can_set_expiry Boolean
        "Whether the user can set the expiry settings of the link. This refers to the ability to
        create a new expiry and modify an existing expiry."
    can_remove_expiry Boolean
        "Whether the user can remove the expiry of the link."
    allow_download Boolean
        "Whether the link can be downloaded or not."
    can_allow_download Boolean
        "Whether the user can allow downloads via the link. This refers to the ability to remove a
        no-download restriction on the link."
    can_disallow_download Boolean
        "Whether the user can disallow downloads via the link. This refers to the ability to impose
        a no-download restriction on the link."
    allow_comments Boolean
        @common.Deprecated
        "Whether comments are enabled for the linked file. This takes the team commenting policy into account."
    team_restricts_comments Boolean
        @common.Deprecated
        "Whether the team has disabled commenting globally."
    audience_options List(LinkAudienceOption)?
        "A list of link audience options the user might be able to set as the new audience."
    can_set_password Boolean?
        "Whether the user can set a password for the link."
    can_remove_password Boolean?
        "Whether the user can remove the password of the link."
    require_password Boolean?
        "Whether the user is required to provide a password to view the link."
    can_use_extended_sharing_controls Boolean?
        "Whether the user can use extended sharing controls, based on their account type."
    can_sync Boolean?
        "Whether a user can save the content to their Dropbox account."
    can_request_access Boolean?
        "Whether the user can request access to the content."
    enforce_shared_link_password_policy team_policies.EnforceLinkPasswordPolicy?
        "Whether the updated externally available shared link must have password set.
        Not provided if the link is not team owned."
    days_to_expire_policy team_policies.DefaultLinkExpirationDaysPolicy?
        "Existing owning team's policy for default number of days from today to link's expiration.
        Not provided if the link is not team owned."
    change_shared_link_expiration_policy ChangeLinkExpirationPolicy?
        "When owning team's policy :field:`change_shared_link_expiration_policy` is :field:`ChangeLinkExpirationPolicy.not_allowed`,
        the updated externally available shared link expiration value cannot be less strict
        than :field:`days_to_expire_policy`.
        In this case :field:`days_to_expire_policy` is expected to be different from `none`.
        Not provided if the link is not team owned."

    example default
        resolved_visibility = public
        can_revoke = false
        revoke_failure_reason = owner_only
        visibility_policies = [public, password]
        can_set_expiry = false
        can_remove_expiry = false
        allow_download = true
        can_allow_download = true
        can_disallow_download = false
        allow_comments = true
        team_restricts_comments = true
        audience_options = [public, team, no_one]
        can_set_password = true
        can_remove_password = true
        require_password = false
        can_use_extended_sharing_controls = false

struct ListSharedLinksArg
    path ReadPath?
        "See :route:`list_shared_links` description."
    cursor String?
        "The cursor returned by your last call to :route:`list_shared_links`."
    direct_only Boolean?
        "See :route:`list_shared_links` description."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

    example path
        path = "/Homework/Math"

    example id
        path = "id:a4ayc_80_OEAAAAAAAAAYa"

    example rev
        path = "rev:a1c10ce0dd78"

    example id_no_parent_links
        path = "id:a4ayc_80_OEAAAAAAAAAYa"
        direct_only = true

struct ListSharedLinksResult
    links List(SharedLinkMetadata)
        "Shared links applicable to the path argument."
    has_more Boolean
        "Is true if there are additional shared links that have not been returned
        yet. Pass the cursor into :route:`list_shared_links` to retrieve them."
    cursor String?
        "Pass the cursor into :route:`list_shared_links` to obtain the additional links. Cursor is
        returned only if no path is given."

    example default
        links = [default]
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
        has_more = true

struct ModifySharedLinkSettingsArgs
    url String
        "URL of the shared link to change its settings."
    settings SharedLinkSettings
        "Set of settings for the shared link."
    remove_expiration Boolean = false
        "If set to true, removes the expiration of the shared link."

    example default
        url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
        settings = default

struct PathLinkMetadata extends LinkMetadata
    "Metadata for a path-based shared link."
    path String
        "Path in user's Dropbox."

    example default
        url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
        path = "/Homework/Math/Prime_Numbers.txt"
        expires = null
        visibility = public

struct RevokeSharedLinkArg
    url String
        "URL of the shared link."

    example default
        url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"

struct SharedLinkSettings
    require_password Boolean?
        "Boolean flag to enable or disable password protection."
    link_password String?
        "If :field:`require_password` is true, this is needed
        to specify the password to access the link."
    expires common.DropboxTimestamp?
        "Expiration time of the shared link. By default the link won't expire."
    audience LinkAudience?
        "The new audience who can benefit from the access level specified by the link's access level
        specified in the `link_access_level` field of `LinkPermissions`. This is used in conjunction
        with team policies and shared folder policies to determine the final effective audience type
        in the `effective_audience` field of `LinkPermissions."
    access RequestedLinkAccessLevel?
        "Requested access level you want the audience to gain from this link. Note, modifying access
        level for an existing link is not supported."
    requested_visibility RequestedVisibility?
        @common.Deprecated
        "Use :field:`audience` instead.  The requested access for this shared link."
    allow_download Boolean?
        "Boolean flag to allow or not download capabilities for shared links."

    example default
        requested_visibility = public
        audience = public
        access = viewer
        allow_download = true

struct TeamMemberInfo
    "Information about a team member."
    team_info TeamInfo
        "Information about the member's team."
    display_name String
        "The display name of the user."
    member_id String?
        "ID of user as a member of a team. This field will only be present if the member is in the
        same team as current user."

    example default
        team_info = default
        display_name = "Roger Rabbit"
        member_id = "dbmid:abcd1234"

struct VisibilityPolicy
    policy RequestedVisibility
        "This is the value to submit when saving the visibility setting."
    resolved_policy AlphaResolvedVisibility
        "This is what the effective policy would be, if you selected this option. The resolved
        policy is obtained after considering external effects such as shared folder settings and
        team policy. This value is guaranteed to be provided."
    allowed Boolean
        "Whether the user is permitted to set the visibility to this policy."
    disallowed_reason VisibilityPolicyDisallowedReason?
        "If :field:`allowed` is :val:`false`, this will provide the reason that the user is not
        permitted to set the visibility to this policy."

    example public
        policy = public
        resolved_policy = public
        allowed = true

    example public_team
        policy = public
        resolved_policy = team_only
        allowed = false
        disallowed_reason = restricted_by_team

    example public_shared_folder
        policy = public
        resolved_policy = shared_folder_only
        allowed = false
        disallowed_reason = restricted_by_shared_folder

    example password
        policy = password
        resolved_policy = password
        allowed = true

    example password_team
        policy = password
        resolved_policy = team_and_password
        allowed = true

    example password_shared_folder
        policy = password
        resolved_policy = shared_folder_only
        allowed = false
        disallowed_reason = restricted_by_shared_folder

    example team_only
        policy = team_only
        resolved_policy = team_only
        allowed = true

    example team_shared_folder
        policy = team_only
        resolved_policy = shared_folder_only
        allowed = false
        disallowed_reason = restricted_by_shared_folder


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


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
        auth = "user"
        scope = "sharing.read"
        select_admin_mode = "whole_team"


route add_file_member (AddFileMemberArgs, List(FileMemberActionResult), AddFileMemberError)
    "Adds specified members to a file."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route get_file_metadata/batch (GetFileMetadataBatchArg, List(GetFileMetadataBatchResult), SharingUserError)
    "Returns shared file metadata."

    attrs
        auth = "user"
        scope = "sharing.read"
        select_admin_mode = "team_admin"

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
        auth = "user"
        scope = "sharing.read"
        select_admin_mode = "whole_team"

route list_received_files (ListFilesArg, ListFilesResult, SharingUserError)
    "Returns a list of all files shared with current user."

    attrs
        auth = "user"
        scope = "sharing.read"
        select_admin_mode = "team_admin"

route list_received_files/continue (ListFilesContinueArg, ListFilesResult, ListFilesContinueError)
    "Get more results with a cursor from :route:`list_received_files`."

    attrs
        auth = "user"
        scope = "sharing.read"

route remove_file_member (RemoveFileMemberArg, FileMemberActionIndividualResult, RemoveFileMemberError) deprecated
    "Identical to remove_file_member_2 but with less information returned."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route remove_file_member_2 (RemoveFileMemberArg, FileMemberRemoveActionResult, RemoveFileMemberError)
    "Removes a specified member from the file."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route relinquish_file_membership (RelinquishFileMembershipArg, Void, RelinquishFileMembershipError)
    "The current user relinquishes their membership in the designated file."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route relinquish_access (RelinquishAccessArg, RelinquishAccessResult, RelinquishAccessError)
    "Removes all self-removable access from a file or folder for the current
    user. Best-effort and idempotent: attempts to drop link-visitor associations
    and explicit ACL membership."

    attrs
        allow_app_folder_app = true
        auth = "user"
        scope = "private:sharing.write"
        select_admin_mode = "whole_team"

route unshare_file (UnshareFileArg, Void, UnshareFileError)
    "Remove all members from this file. Does not remove inherited members."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route update_file_member (UpdateFileMemberArgs, MemberAccessLevelResult, FileMemberActionError)
    "Changes a member's access on a shared file."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route update_file_policy (UpdateFilePolicyArg, SharedFileMetadata, UpdateFilePolicyError)
    "Update the viewer info policy of a file."

    attrs
        auth = "user"
        scope = "sharing.write"


alias PathOrId = String(min_length=1, pattern="((\/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")

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."
    banned_member
        "The current user has been banned for abuse reasons."

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
        @common.Deprecated
        "Use create_view_link and create_edit_link instead."
    create_link
        @common.Deprecated
        "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

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

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

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 GetFileMetadataError
    "Error result for :route:`get_file_metadata`."
    user_error SharingUserError
    access_error SharingFileAccessError

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

union ListFileMembersContinueError
    "Error for :route:`list_file_members/continue`."
    user_error SharingUserError
    access_error SharingFileAccessError
    invalid_cursor
        ":field:`ListFileMembersContinueArg.cursor` is invalid."

union ListFileMembersError
    "Error for :route:`list_file_members`."
    user_error SharingUserError
    access_error SharingFileAccessError

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

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

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

union RelinquishAccessError
    "Error result for the relinquish_access endpoint."
    invalid_file_id
        "File or folder not found or has been deleted."
    email_unverified
        "Caller's email address is not verified."
    owner
        "User is the owner of the file/folder."
    no_explicit_access
        "User has only non-removable access — inherited from a parent folder
        or via group membership. Either way, relinquish_access cannot remove
        the caller's access from this surface; the caller must take action
        on the source of the access (e.g. leave the parent shared folder,
        or be removed from the group)."
    team_folder
        "Team folder restrictions apply."
    no_permission
        "Caller does not have permission to perform this action. Generic fallback."

union UpdateFilePolicyError
    "Error result for :route:`update_file_policy`."
    access_error SharingFileAccessError
    invalid_file_settings
        "The file settings are invalid."
    no_permission
        "The current user does not have permission to perform this action."

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 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 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 UnshareFileError
    "Error result for :route:`unshare_file`."
    user_error SharingUserError
    access_error SharingFileAccessError

    example default
        user_error = email_unverified

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?
        "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. Only meant for Paper files."
    fp_sealed_result String?
        "The FingerprintJS Sealed Client Result value"

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"
        members = [default]
        custom_message = "This is a custom message about ACME.doc"
        quiet = false
        access_level = viewer

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"]

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 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 = []

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

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(max_value=300, min_value=1) = 100
        "Number of members to return max per query. Defaults to 100 if no limit is specified."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"

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=3000) = 1000
        "Number of members to return max per query. Defaults to 1000 if no limit is specified."

    example default
        files = ["id:3kmLmQFnf1AAAAAAAAAAAw","id:VvTaJu2VZzAAAAAAAAAADQ"]
        limit = 1000

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 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"

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

struct ListFilesArg
    "Arguments for :route:`list_received_files`."
    limit UInt32(max_value=300, min_value=1) = 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 ListFilesContinueArg
    "Arguments for :route:`list_received_files/continue`."
    cursor String
        "Cursor in :field:`ListFilesResult.cursor`."

    example default
        cursor = "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9emfGRlc2MCRWxpbWl0BGRId"

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"

struct RelinquishFileMembershipArg
    file PathOrId
        "The path or id for the file."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"

struct RelinquishAccessArg
    "Removes all self-removable access from a file or folder.
    For folders: always relinquishes without keeping a local copy
    (leave_a_copy=false behavior). If you need control over keeping
    folder contents, use the relinquish_folder_membership endpoint instead."
    file_id String
        "The id for the file or folder."

    example default
        file_id = "id:3kmLmQFnf1AAAAAAAAAAAw"

struct RelinquishAccessResult
    "Returns an empty response for the relinquish_access endpoint."

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

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]

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

struct UnshareFileArg
    "Arguments for :route:`unshare_file`."
    file PathOrId
        "The file to unshare."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"

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

struct UpdateFilePolicyArg
    "Arguments for :route:`update_file_policy`."
    file PathOrId
        "File that we are changing the policy for."
    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."
    link_settings LinkSettings?
        @common.Deprecated
        "Settings on the link for the file."
    viewer_info_policy ViewerInfoPolicy?
        "The presence and seen state policy on the file."

    example default
        file = "/root/word.docx"

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


alias DropboxId = String(min_length=1)

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."
    team_and_approved
        "Only a teammate and approved people can become a member."

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
        @common.Deprecated
        "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."

union ViewerInfoPolicy
    enabled
        "Viewer information is available on this file."
    disabled
        "Viewer information is disabled on this file."

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
        @common.Deprecated
        "Use create_view_link and create_edit_link instead."
    create_link
        @common.Deprecated
        "Use create_view_link and create_edit_link instead."
    create_view_link
        "Create a shared link that only allows users to view the content."
    create_edit_link
        "Create a shared link that allows users to edit the content."
    set_access_inheritance
        "Set whether the folder inherits permissions from its parent."

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"


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

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"

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

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 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 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?
        @common.Deprecated
        "Never set."
    is_inherited Boolean = false
        "True if the member has access on a parent folder."

    example default
        access_type = owner
        permissions = []
        initials = "JD"
        is_inherited = false

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
        @common.Deprecated
        "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 = []

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

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 = 0
        "The value is the member limit that was reached."
    too_many_pending_invites UInt64 = 0
        "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
        @common.Deprecated
        "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."
    invalid_group
        "Provided group is invalid."
    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"

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

union_closed JobStatus extends async.PollResultBase
    complete
        "The asynchronous job has finished."
    failed JobError
        "The asynchronous job returned an error."

union ListFolderMembersContinueError
    access_error SharedFolderAccessError
    invalid_cursor
        ":field:`ListFolderMembersContinueArg.cursor` is invalid."

union ListFoldersContinueError
    invalid_cursor
        ":field:`ListFoldersContinueArg.cursor` is invalid."

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."
    must_automount
        "The shared folder is not mountable by directly call APIs, instead the
        automounter is responsible for mounting it."

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

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

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

union ShareFolderError extends ShareFolderErrorBase
    no_permission
        "The current user does not have permission to perform this action."

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 or group sharing settings are 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 ShareFolderErrorBaseV2
    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`."
    team_policy_disallows_member_policy
        "Team policy or group sharing settings are 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 ShareFolderErrorV2 extends ShareFolderErrorBaseV2
    no_permission
        "The current user does not have permission to perform this action."

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

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 SharePathErrorBaseV2
    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_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."

union SharePathErrorV2 extends SharePathErrorBaseV2
    is_family
        "We do not support sharing the Family folder."
    contains_app_folder
        "We do not support shared folders that contain app folders."

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
        @common.Deprecated
        "Never set."
    unmounted
        "The shared folder is unmounted."

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

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

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

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

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 or group sharing settings are 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."

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."
    fp_sealed_result String?
        "The FingerprintJS Sealed Client Result value"

    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?
        "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

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

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 = []

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

struct ListFolderMembersArgs extends ListFolderMembersCursorArg
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder. When path is provided, the folder ID will be extracted from the path instead."
    path String?
        "Optional path to get inherited members. When omitted, uses shared_folder_id to return direct members.
        When provided, extracts folder ID from this path and returns users who have access through parent shared folder."

    example default
        shared_folder_id = "84528192421"
        actions = []
        limit = 10

    example with_path_id
        shared_folder_id = "67890"
        path = "ns:67890/Documents/Folder"
        actions = []
        limit = 10

    example with_full_path
        shared_folder_id = "84528192421"
        path = "/Users/john/Dropbox/Documents/Folder"
        actions = []
        limit = 10

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"

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(max_value=1000, min_value=1) = 1000
        "The maximum number of results that include members, groups and invitees to return per request."

    example default
        actions = []
        limit = 10

struct ListFoldersArgs
    limit UInt32(max_value=1000, min_value=1) = 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 ListFoldersContinueArg
    cursor String
        "The cursor returned by the previous API call specified in the endpoint description."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

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"

struct MountFolderArg
    shared_folder_id common.SharedFolderId
        "The ID of the shared folder to mount."

    example default
        shared_folder_id = "84528192421"

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

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

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"

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

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 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"

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."
    folder_id files.FileId?
        "The ID of the content."

    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
        folder_id = "id:a4ayc_80_OEAAAAAAAAAXw"

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"

struct UnmountFolderArg
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."

    example default
        shared_folder_id = "84528192421"

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

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

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


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
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route check_job_status (async.PollArg, JobStatus, async.PollError)
    "Returns the status of an asynchronous job."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route check_remove_member_job_status (async.PollArg, RemoveMemberJobStatus, async.PollError)
    "Returns the status of an asynchronous job for sharing a folder."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route check_share_job_status (async.PollArg, ShareFolderJobStatus, async.PollError)
    "Returns the status of an asynchronous job for sharing a folder."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

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
        auth = "user"
        scope = "sharing.read"
        select_admin_mode = "whole_team"

route list_folders (ListFoldersArgs, ListFoldersResult, Void)
    "Return the list of all shared folders the current user has access to."

    attrs
        auth = "user"
        scope = "sharing.read"

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
        auth = "user"
        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
        auth = "user"
        scope = "sharing.read"

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
        auth = "user"
        scope = "sharing.write"

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
        auth = "user"
        scope = "sharing.write"

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
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

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
        auth = "user"
        scope = "sharing.write"

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
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

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
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

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
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route unshare_folder (UnshareFolderArg, async.LaunchEmptyResult, UnshareFolderError)
    "Allows a shared folder owner to unshare the folder.
    Unshare will not work in following cases:
    The shared folder contains shared folders OR the shared folder is inside another shared folder.
    You'll need to call :route:`check_job_status` to determine if the action has
    completed successfully."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

route update_folder_member (UpdateFolderMemberArg, MemberAccessLevelResult, UpdateFolderMemberError)
    "Allows an owner or editor of a shared folder to update another member's
    permissions."

    attrs
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"

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
        auth = "user"
        scope = "sharing.write"
        select_admin_mode = "team_admin"


route get_folder_metadata (GetMetadataArgs, SharedFolderMetadata, SharedFolderAccessError)
    "Returns shared folder metadata by its folder ID."

    attrs
        auth = "user"
        scope = "sharing.read"
        select_admin_mode = "whole_team"

route list_folder_members (ListFolderMembersArgs, SharedFolderMembers, SharedFolderAccessError)
    "Returns shared folder membership by its folder ID."

    attrs
        auth = "user"
        scope = "sharing.read"
        select_admin_mode = "whole_team"

route list_mountable_folders (ListFoldersArgs, ListFoldersResult, Void)
    "Return the list of all shared folders the current user can mount or unmount."

    attrs
        auth = "user"
        scope = "sharing.read"