Shared folder metadata enters production beta

Dropbox is launching a production beta of shared folder metadata functionality in the Core API. Developers can now retrieve additional details about shared folders and their contents, including folder membership, per-user permissions, and last-modified information for individual files. The release is the first step toward full programmatic control over shared folder creation and management.

The new metadata also introduces a read_only field on shared folders and the files inside them. This field supports the recently announced view-only permission tier and returns true when the authenticated user cannot write to files in the shared folder.

Although the feature is in beta, it is designated as a production beta, meaning Dropbox considers it stable enough for use in production apps with real users. Access requires completing the beta request form.

Trying out the metadata

A demo application is available at sfmdemo.herokuapp.com that lets you browse shared folders and inspect their metadata. The full source is published on GitHub at github.com/dropbox/sfmdemo.

New endpoint and metadata fields

The main API addition is the /shared_folders endpoint, which returns either a list of a user's shared folders or details about one specific folder. The endpoint is not yet wrapped in the official SDKs, but it can be called directly like any Core API endpoint. Here is a sample curl command to fetch a user's shared folders:

curl https://api.dropbox.com/1/shared_folders -H "Authorization:Bearer <YOUR-ACCESS-TOKEN>"

Sample output from that call looks like this:

[
    ...
    {
        "access_type": "owner",
        "owner": {
            "display_name": "Steve Marx",
            "same_team": true,
            "uid": 178508400
        },
        "path": "/sadkittens",
        "shared_folder_id": "457064830",
        "shared_folder_name": "sadkittens"
    }
    ...
]

The access_type field in the response indicates the authenticated user's role in the folder—for instance, an owner in the example above. Users added to a folder owned by someone else will typically appear as an "editor" or "viewer" depending on the assigned permission level.

To retrieve metadata for a single folder, append the folder ID to the endpoint URL. For example, the call with URL https://api.dropbox.com/1/shared_folders/457064830 returns details about that specific shared folder, including its membership.

The beta also augments file and folder metadata returned by all existing metadata endpoints, including /metadata, /delta, /search, and /revisions. The demo uses a /metadata call to list the files in a shared folder alongside the last modifier of each file; selecting an individual file then triggers a /revisions call to show its modification history.

Beta terms and availability

As a production beta, the API is considered stable and can be used in apps with real users. Dropbox plans to extend the functionality based on developer feedback, so the final version may differ slightly from what is available now. Once the API leaves production beta, the beta version will continue to be supported for three months.

Update: Shared folder metadata is no longer in beta and is available to all developers. For usage details, see the demo source code on GitHub and the Core API documentation.