> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.dropboxapi.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dropboxapi.com/_mcp/server. # File Access Welcome! If you’re trying to access Dropbox files through the API, then you’re in the right place. This guide is for learning to interact with files by using the Dropbox API. ## Dropbox File Metadata When building with the Dropbox API, *every* file is represented by metadata. Every single file from spreadsheets to cat pictures to shortcuts can be thought of as a JSON object with a set of fields that provide information about the file. Folders also have metadata, which we’ll cover in the List Folder Content section below. When working with files or folders using the Dropbox API, there are specific fields that are commonly used. That’s a great place to start our understanding of file metadata. Let’s take a look at the file data for *random\_cartoon.mp4:* ```json { ".tag": "file", "name": "random_cartoon.mp4", "path_lower": "/videos/random_cartoon.mp4", "path_display": "/Videos/random_cartoon.mp4", "id": "id:odTlUvbpIEAAAAAAAAABmw", "client_modified": "2019-06-28T21:07:10Z", "server_modified": "2020-03-25T15:47:15Z", "rev": "015a1afc851d642000000013f0b5550", "size": 1958858, "is_downloadable": true, "content_hash": "ecf06d09d3cd57caf3c91c81c369cf2f27939d616b550b813703ca40753357e1" } ``` Please refer to the `FileMetadata` type under the [/files/get\_metadata documentation](/dropbox-api/api-reference/user-endpoints/files/get-metadata) for exact property descriptions. We’re leaving out a few of them to focus on certain core properties: * `.tag` is used to quickly distinguish between a file and folder by identifying the underlying type * `id` is used as a *unique* reference to a *specific* file * Note that a new file with the same file name would still be assigned a new `id` * `server_modified` is used to determine when the file was last changed * `rev` is used as a reference to *specific* versions of a file to help with things like change detection * `content_hash` can be used to verify a local version of a file matches the one in Dropbox Optional fields are used to track additional information about the state of a file or folder. For example, if *random\_cartoon.mp4* was placed inside a [shared folder](https://help.dropbox.com/files-folders/share/share-with-others) and then [locked for editing](https://help.dropbox.com/files-folders/share/file-locking), then our metadata would contain both `sharing_info` and `file_lock_info`. ```json { ".tag": "file", "name": "random_cartoon.mp4", // ... "sharing_info": { "read_only": true, "parent_shared_folder_id": "84528192421", "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc" }, // ... "file_lock_info": { "is_lockholder": false, "lockholder_name": "James Bond", "lockholder_account_id": "dbid:AABuXdtqA88UpveXxu7rcTSo64ADcrWnBMk", "created": "2020-03-05T02:28:19Z" } } ``` ## Understanding Paths and Identifiers When using the Dropbox API to interact with a specific file, most [/files/](/dropbox-api/api-reference/user-endpoints/files) endpoints require a `path` that points to a specific file. There are multiple ways to reference a file that can be used as `path` parameter: 1\. File path (e.g. `/Pictures/cats/cat_in_box.png`) * Most “human readable” reference * Dependent on the file name and location staying the same * Best choice for referencing a file by name in a specific location 2\. File id (e.g. `id:odTlUvbpIEFAAAAAAAAGOQ`) * Unique file reference that persists if files are moved or renamed * Useful for apps referencing files that are moved around * Best choice for reliable, accurate reference to a *specific* file 3\. File revision (e.g. `rev:015a01044acb99900000001aa8954d0`) * References a *specific version* of a file * Useful for version control, restoring deleted files, and managing conflicting copies * Best choice for referencing a file at a specific point in time 4\. Namespace-relative file path (e.g. `ns:1522576049/cats/cat_in_box.png`) * References a file in a specific namespace, which is a unique permission space * Useful for referencing files in shared folders mounted in different locations for each user * Best choice for admins using the Dropbox-API-Select-Admin header Consider how your app needs to interact with Dropbox files and choose the best file reference for your needs. ## Traversing Files and Folders You can list contents of a Dropbox folder with the [/files/list\_folder](/dropbox-api/api-reference/user-endpoints/files/list-folder) endpoint, which accepts a folder’s `path` and returns the content of that folder in an `entries` array along with a `cursor` for retrieving additional results with [/files/list\_folder/continue](/dropbox-api/api-reference/user-endpoints/files/list-folder-continue). Using the `recursive` argument will return content of subfolders, which simplifies traversal. In addition to a folder’s path (e.g. /Homework/math), the `path` parameter will also accept: * a folder’s id (e.g. `id:odTlUvbpIEAAAAAAAAAGGQ`) * a folder path scoped to a specific namespace (e.g. `ns:1521576049/Homework/math`) Example /files/list\_folder output: ```json { "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 } ``` When listing folder content, you should *always* check the `has_more` flag. If it’s `true`, then your results have been paginated and you’ll need to call [/files/list\_folder/continue](/dropbox-api/api-reference/user-endpoints/files/list-folder-continue) with the `cursor` from your response. ### Access Rights The access rights of the content is returned in the `sharing_info` field of the file’s metadata. The field is optional and appears on files that inside of shared folders. * `read_only` — If true, the content of the shared folder is readable, but can’t be modified by the user. * `traverse_only` — If true, the user only has traversal rights on the folder. Calling /files/list\_folder on that folder will only return the subset of paths that the user can access. * `no_access` — If true, the user may see that the folder exists, but any attempts to view its’ contents will return an error. ### Deleted Content You can modify your /files/list\_folder call to include deleted content by setting `include_deleted` to `true`. The deleted content inside the folder may be available for recovery as allowed by [revision history](https://www.dropbox.com/features/cloud-storage/file-recovery-and-history) retention. You can download the deleted content by calling [/files/download](/dropbox-api/api-reference/user-endpoints/files/download) and specifying the [revision](/dropbox-api/api-reference/user-endpoints/files/list-revisions) as the `path` parameter. There is an example revision reference farther down in this guide. ### List Folder Content Exercise: * Go to the [/files/list\_folder endpoint in the API Explorer](https://dropbox.github.io/dropbox-api-v2-explorer/#files_list_folder) * Select ‘Get Token’ to populate a short-lived token * Put in a path to a Dropbox folder that you know has nested folders inside it * Set the `recursive` parameter to `true` and click ‘Submit Call’ * Examine the response. Where’s all the content information? It may be on the next page of results. * Copy the `cursor` from your response * Navigate to [/files/list\_folder/continue in the API Explorer](https://dropbox.github.io/dropbox-api-v2-explorer/#files_list_folder/continue) * Paste your `cursor` and click ‘Submit Call’ Congratulations! The mechanisms that you just practiced are an essential part of building world class Dropbox applications. If you find yourself struggling when trying to list folder content, try using the [API Explorer](https://dropbox.github.io/dropbox-api-v2-explorer) to practice and tweak parameters until you find the right behavior. ## Files That Require Special Consideration When working with files using the Dropbox API, there are two special cases to be aware of: non-downloadable files and files that have been locked for editing. Both types of files may require additional logic in your app. ### Non-downloadable Files The majority of file types in Dropbox can be downloaded. However, certain types of files are only editable in the cloud and are considered non-downloadable. That includes [Google documents](https://help.dropbox.com/installs-integrations/third-party/create-google-docs) (Docs, Sheets, or Slides), [Dropbox Paper](https://help.dropbox.com/files-folders/paper), and [Microsoft Office docs](https://help.dropbox.com/files-folders/share/edit-microsoft-office-documents). Non-downloadable files can be *exported* instead of downloaded using [/files/export](/dropbox-api/api-reference/user-endpoints/files/export). ### Locked Files Files inside shared folders can be locked when a user wants to prevent unwanted edits. When you need to perform actions on a locked file, you’ll need to unlock it. However, the unlock can only be issued by either the lock holder or an admin. Both approaches are covered in the developer blog article called [“File locking using the Dropbox API”](https://dropbox.tech/developers/file-locking-using-the-dropbox-api). ## Best Practices for Working With Files When working with Dropbox files, there are some specific use cases that have best practices. Note that we may update this section in the future. ### Content Hashing When you need to verify that the server’s copy of a file is the same as your local version of the file, you can use the file’s `content_hash`, which is included in the properties of every file’s metadata. ```json { ".tag": "file", // other file properties "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ``` The `content_hash` allows you to compare file versions *without* downloading them by computing your own `content_hash` locally. You can find step-by-step instructions on computing your own `content_hash` in our [Content Hash Guide](/dropbox-api/docs/technical-reference/content-hash). ### Previewing Files Pulling large files into your app each time a user needs to preview their Dropbox content can consume a lot of bandwidth; slowing your app down and negatively impacting your user’s experience. Thankfully, the Dropbox API offers two endpoints to help retrieve content: [/files/get\_thumbnail](/dropbox-api/api-reference/user-endpoints/files/get-thumbnail) and [/files/get\_preview](/dropbox-api/api-reference/user-endpoints/files/get-preview). Need to preview an image? The [/files/get\_thumbnail](/dropbox-api/api-reference/user-endpoints/files/get-thumbnail) endpoint works with most image files and provides parameters to configure the thumbnail’s file type and scaling behavior. Generating multiple thumbnails in bulk with [/files/get\_thumbnail\_batch](/dropbox-api/api-reference/user-endpoints/files/get-thumbnail-batch) can further enhance your app’s performance. Need to preview a file? The [/files/get\_preview](/dropbox-api/api-reference/user-endpoints/files/get-preview) endpoint generates previews of many types of files. A PDF preview is generated for most multi-page doc files (.pptx, .docx, .ai, .gslides, etc.) while HTML previews are generated for other types of files (.gsheet, .xlsx, .csv).