Content Access Guide

This guide covers advanced topics relating to scanning content and monitoring changes within Dropbox accounts. This guide assumes familiarity with namespaces, and explains permissions, deletion & revisions, and detecting updates in greater detail.

Files & Folders

Certain types of applications may need to perform an initial scan of all content in a path to detect current state. In order to do so, it is important to be aware of access rights and how deleted and unmounted content is represented.

List Folder Content

To enumerate content in a path in a Dropbox Account, use the files/list_folder call. The method will list file and folder metadata, and return a cursor for retrieving additional results with files/list_folder/continue. Using the recursive argument will return content of subfolders, which simplifies traversal.

Example files/list_folder output:

{
    "entries": [
        {
            ".tag": "file",
            "name": "Prime_Numbers.txt",
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "client_modified": "2015-05-12T15:50:38Z",
            "server_modified": "2015-05-12T15:50:38Z",
            "rev": "a1c10ce0dd78",
            "size": 7212,
            "path_lower": "/homework/math/prime_numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "sharing_info": {
                "read_only": true,
                "parent_shared_folder_id": "84528192421",
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
            },
            "has_explicit_shared_members": false,
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        },
        {
            ".tag": "folder",
            "name": "math",
            "id": "id:a4ayc_80_OEAAAAAAAAAXz",
            "path_lower": "/homework/math",
            "path_display": "/Homework/math",
            "sharing_info": {
                "read_only": false,
                "parent_shared_folder_id": "84528192421",
                "traverse_only": false,
                "no_access": false
            }
        }
    ],
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "has_more": false
}

Files are uniquely identified by their file_id, and their folder access permissions by the shared_folder_id they are contained in.

Note that the same shared content can have different relative paths for different users (see the namespace guide for an example). As such, referring to content by identifiers rather than relative paths in other API calls is generally recommended - especially for team applications.

Access Rights

The access rights of the content is returned within the sharing_info of the file metadata.

  • read-only: If true, the content of shared folder is readable, but not modifiable by the user.
  • traverse-only: If true, the user only has traversal rights on the folder. Explicitly enumerating the folder with list_folder will only return the subset of paths the user has access to.
  • no_access: If true, the user may see the that the folder exists - but attempts to view its contents will return an error.

The absence of sharing_info on a file or folder indicates that it is unshared content, accessible only by the user.

Unmounted Content

The files/list_folder call will only list mounted content. This consists of the users private content and available shares mounted to the user's Dropbox Account. The user may have access to additional shared folders, which are not mounted due to either not acting on a shared invite or by explicitly un-mounting it. See the end user documentation here.

The list of these available shares is returned by sharing/list_mountable_folders. The path_lower property indicates the mount point, and the absence of the property indicates the share is unmounted. These shares will be available until explicitly left or unshared.

Deleted Content

The user may have access to prior versions of and/or deleted content which they may be able to restore. Deleted content is visible in files/list_folder calls by passing include_deleted:true, and downloadable with the files/download call by specifying revision. Deleted content is available for recovery as allowed by revision history retention, or until permanent deletion.

Sharing

Dropbox file content can be shared via links, shared folders, and explicit file sharing - all of which have corresponding API calls. See the end user documentation here.

Content may be shared via a shared link. These shared links are typically publicly accessible by default, but may be set to expire and/or have their visibility limited to logged-in team members or to those with the password. The sharing/list_shared_links endpoint will return all shared links created by the user.

Example sharing/list_shared_links output:

{
    "entries": [
        {
            "id": "id:3kmLmQFnf1AAAAAAAAAAAw",
            "name": "file.txt",
            "policy": {
                "acl_update_policy": { ".tag": "owner" },
                "shared_link_policy": { ".tag": "anyone" },
                "member_policy": { ".tag": "anyone" },
                "resolved_member_policy": { ".tag": "team" }
            },
            "preview_url": "https://www.dropbox.com/scl/fi/fir9vjelf",
            "access_type": { ".tag": "viewer" },
            "owner_display_names": [ "Jane Doe" ],
            "owner_team": {
                "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
                "name": "Acme, Inc."
            },
            "path_display": "/dir/file.txt",
            "path_lower": "/dir/file.txt",
            "permissions": [],
            "time_invited": "2016-01-20T00:00:00Z"
        }
    ],
    "cursor": "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9cmV2aXNpb24H3Qf6o1fkHxQ"
}

Shared Folders

Content may be shared via a shared folder. The list of shared folders a user has access to can be enumerated by the sharing/list_folders call, and their membership with sharing/list_folder_members.

Shared folders may have an owner, and any number of viewers and editors. These may be individual users or groups. Folders have policies around scope of membership, ACL modifications, and links, which is also returned with folder metadata.

Example sharing/list_folders output:

{
    "entries": [
        {
            "access_type": { ".tag": "owner" },
            "is_inside_team_folder": false,
            "is_team_folder": false,
            "name": "dir",
            "policy": {
                "acl_update_policy": { ".tag": "owner" },
                "shared_link_policy": { ".tag": "anyone" },
                "member_policy": { ".tag": "anyone"},
                "resolved_member_policy": { ".tag": "team" }
            },
            "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
            "shared_folder_id": "84528192421",
            "time_invited": "2016-01-20T00:00:00Z",
            "path_lower": "/dir",
            "link_metadata": {
                "audience_options": [
                    { ".tag": "public" },
                    { ".tag": "team" },
                    { ".tag": "members" }
                ],
                "current_audience": { ".tag": "public" },
                "link_permissions": [
                    {
                        "action": { ".tag": "change_audience" },
                        "allow": true
                    }
                ],
                "password_protected": false,
                "url": ""
            },
            "permissions": [],
            "access_inheritance": {
                ".tag": "inherit"
            }
        }
    ],
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}

Dropbox Business teams also have access to team folders. Team folders behave similarly to shared folders (and API calls to shared folders), with two key distinctions:

  • • Team folders are logically owned by the team, and some mutating calls (creation, archival) are performed with the Business API.
  • • Team folders may have nested shares within them. Shares nested within a team folder inherit the permissions of the team folder by default.

Prior to the Team Space, team folders were automatically mounted in the member's Dropbox account. With team space, the team space is represented as a team folder that the member folder is rooted to. See our namespace guide for more detail.

Explicit File Sharing

Files may be explicitly shared with other users, without a shared link or shared folder. The list of files that have been explicitly shared with the user may be retrieved by the sharing/list_received_files endpoint.

Example sharing/list_recived_files output:

{
    "entries": [
        {
            "id": "id:3kmLmQFnf1AAAAAAAAAAAw",
            "name": "file.txt",
            "policy": {
                "acl_update_policy": { ".tag": "owner" },
                "shared_link_policy": { ".tag": "anyone" },
                "member_policy": { ".tag": "anyone" },
                "resolved_member_policy": { ".tag": "team" }
            },
            "preview_url": "https://www.dropbox.com/scl/fi/fir9vjelf",
            "access_type": { ".tag": "viewer" },
            "owner_display_names": [ "Jane Doe" ],
            "owner_team": {
                "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
                "name": "Acme, Inc."
            },
            "path_display": "/dir/file.txt",
            "path_lower": "/dir/file.txt",
            "permissions": [],
            "time_invited": "2016-01-20T00:00:00Z"
        }
    ],
    "cursor": "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9cmV2aXNpb24H3Qf6o1fkHxQ"
}

The list of files shared by the user does not have a direct enumeration call - instead the list_folder call can be passed the include_has_explicit_shared_members parameter, which will return a boolean indicating if content has explicit shares. The membership of the explicit share can be viewed with the sharing/list_file_members call.

Detecting Updates

Certain types of applications will need to detect changes relative to a given path going forward, and the Dropbox API provides several mechanisms of doing so.

Cursors

Many of Dropbox's list calls described above utilize cursors, which sequentially read through results. A cursor is a pagination mechanism that will return results up to the specified limit, a boolean indicating if more results are available, and a new cursor to retrieve the next page.

Many API calls, such as sharing/list_shared_links, are intended for pagination and will only return a cursor if there are additional pages of results.

However, the cursor returned by files/list_folder is designed for long term polling as well. Once has_more returns false, the cursor that is returned can be used to poll for additional updates Files added, edited, or deleted since the time the cursor was created will be returned (other metadata changes, like an ACL change, will not be included) in continue calls.

The files/list_folder/get_latest_cursor call will return the latest cursor, which can be used to monitor for changes starting at the time the cursor was created.

Webhooks

Webhooks allow you to receive HTTP POST notifications on changes, which will allow your application to efficiently listen for changes rather than poll the endpoint.

Currently, webhooks are available for file operations and work in conjunction with list_folder. Webhooks will provide your application with a list of users whom have file changes, such that you may call files/list_folder with the prior cursor value you have stored to retrieve updates.

Team Events

For team-linked applications, the team_log/get_events API is the best mechanism for detecting all changes that have occurred on the business team - including content, permissions, and team settings.

The events API provides a series of filters for specifying time range and event category type, and a rich schema with identifiers describing the exact change. Like list_folder, the cursor from returned call can be used to poll for changes.

Example team_log/get_events entry:

        {
            "timestamp": "2017-08-14T06:49:20Z",
            "event_category": { ".tag": "file_operations" },
            "actor": {
                ".tag": "user",
                "user": {
                    ".tag": "team_member",
                    "account_id": "dbid:ABCDMCvPlupS23WsLcsxD1q0I-fTX7gxRw",
                    "display_name": "John Smith",
                    "email": "john@acme.com",
                    "team_member_id": "dbmid:ABCD_JXBjElUPaMLW7XewoH7F1euVwLQceo"
                }
            },
            "origin": {
                "geo_location": {
                    "city": "San Francisco",
                    "region": "California",
                    "country": "US",
                    "ip_address": "123.123.123.123"
                },
                "host": {
                    "host_id": 1000000000
                },
                "access_method": {
                    ".tag": "end_user",
                    "end_user": { ".tag": "web" }
                }
            },
            "involve_non_team_member": false,
            "context": {
                ".tag": "team_member",
                "account_id": "dbid:ABCDMCvPlupS23WsLcsxD1q0I-fTX7gxRw",
                "display_name": "John Smith",
                "email": "john@acme.com",
                "team_member_id": "dbmid:ABCD_JXBjElUPaMLW7XewoH7F1euVwLQceo"
            },
            "assets": [
                {
                    ".tag": "file",
                    "path": {
                        "contextual": "/folder/office.jpg",
                        "namespace_relative": {
                            "ns_id": "1122112231",
                            "relative_path":"office.jpg"
                        }
                    },
                    "file_id": "id:1111111111AAAAAAAAAAAA",
                }
            ],
            "event_type": {
                ".tag": "file_add",
                "description":"Added files and/or folders."
            },
            "details": { ".tag": "file_add_details" }
        }

For applications that need to determine current state, replaying all event logs tends to be inefficient. In these scenarios, use the corresponding list calls to determine current state - then specify a start time to the event log to look for subsequent changes.

See the team_log/get_events documentation for more information on individual events.

Best Practices

Here are a few more recommendations and related functionality that will help you work with Dropbox content.

Team Content

Both user-linked and team-linked applications may wish to access the Team Space, which is a shared workspace available to some Dropbox Business Teams. Accessing this space requires passing the Dropbox-API-Path-Root header. See the namespace guide for more information.

In a team-linked application, the user calls described in this guide can be executed by an administrator on behalf of an individual member using the Dropbox-API-Select-User API header For a team-centric view of content, the team/namespaces/list call will list unique permission spaces available to the team, which are easily accessed as an administrator using the Dropbox-API-Select-Admin header. See the Business API documentation for more information on Select-User and Select-Admin.

Keeping State with Properties

Dropbox file properties can allow your application to keep state variables on Dropbox files directly, simplifying implementation. Dropbox file templates are currently visible to the application which created them.

Paper

Dropbox Paper documents are not represented in the files/list_folder calls. Paper documents may be enumerated with the analgous paper/docs/list call.

Similarly, a Dropbox paper document's explicit membership can be accessed via paper/users/list, and it's inherited membership through folders can be retrieved with paper/docs/get_folder_info and paper/docs/folder_users/list (respectively).