API v1 → v2 Migration guide

The following guide will help you migrate from API v1's "Core API" and "Dropbox for Business API" to API v2.

Note: In v1, there was a "Core API" with several SDKs, and a "Dropbox for Business API." In API v2, "the API" and "Dropbox Platform" refer to both of them; it encompasses the endpoints for user and team apps.

Migration checklist for developers

Check whether you need to migrate your user's access tokens or re-authenticate with a new permission.
Familiarize yourself with the new v2 syntax. Read up on the patterns of v2 endpoints, do a tutorial for an SDK, and test-drive v2 calls with your own data in the API Explorer.
Figure out which v1 endpoints your app uses, and look up the equivalent ones in API v2 using our v1 → v2 mapping table.
Update your app's code, replacing API v1 calls with API v2 calls.
Update the error handling in your app to utilize v2 errors.

Endpoints: v1 → v2 mapping

Here's a mapping of how v1 functionality maps to v2. All v1 endpoints are listed in the left column, and the equivalent v2 endpoints are in the right column. Some endpoints take different parameters or return different data; make sure you check out the full documentation when that's noted. Not all v2 endpoints are listed here.

OAuth

Note: API v2 only uses OAuth 2. The new endpoints do not have the /2 prefix, but rather, just begin with /oauth2.

v1	v2
/1/oauth2/authorize	/oauth2/authorize
/1/oauth2/token	/oauth2/token
/1/oauth2/token_from_oauth1	/2/auth/token/from_oauth1
/1/disable_access_token	/2/auth/token/revoke

Users and account information

Note: In v1, user accounts included a uid field, an integer that represented a user's Dropbox ID. In v2, we use account_id, which is a string that represents the user's unique Dropbox ID. An account_id value begins with the prefix "dbid" for an individual Dropbox account. Business accounts also have team_member_ids, which begin with the prefix "dbmid." To map uids to account_ids, use an access token to make a call to /2/users/get_current_account, and map that value to the value you get from /1/account/info.

/1/account/info

/2/users/get_current_account

Note: Parameters and return values have changed. Please refer to the full documentation for details.

Tip: The following return values have moved:

v1	v2
quota_info/quota	allocation (Returned by /2/users/get_space_usage)
quota_info/normal	used (Returned by /2/users/get_space_usage)

Getting information about files and folders

Tip: Did you know that API v2 now has file IDs? With v2, you can now use a file ID instead of path when working with files, which means that you won't lose track of a file even if a user moves or renames it.

v1	v2
/1/delta	/2/files/list_folder (with recursive=true) Note: Parameters and return values have changed. Please refer to the full documentation for details. Tip: In v1, a call to /delta returned "delta entries." In v2, it will return a list of Metadata objects. See below on how to map the v1 return values to v2 metadata. Note: The equivalent of v1's /delta is /files/list_folder with recursive=true. In v1, if the initial call doesn't contain all of the results, you would use the returned cursor to make another call to /delta; in v2, you will use the returned cursor to make a call to /2/files/list_folder/continue. Tip: You can use a cursor returned from v1's /1/delta in calls to v2's /files/list_folder/continue.
/1/delta/latest_cursor	/2/files/list_folder/get_latest_cursor
/1/longpoll_delta	/2/files/list_folder/longpoll
/1/metadata	/2/files/get_metadata Note: Parameters and return values have changed. Please refer to the full documentation for details. Note: The equivalent of v1's /metadata with list=true to get the contents is /files/list_folder. In v2, if the initial call doesn't contain all of the results you will use the returned cursor to make a call to /2/files/list_folder/continue. Tip: The v1 endpoint /metadata returned v1-style metadata. In v2, /files/get_metadata will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.
/1/metadata/link	/2/sharing/get_shared_link_metadata Note: Parameters and return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /metadata/link returned v1-style metadata. In v2, /sharing/get_shared_link_metadata will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata. Tip: To list contents under a folder shared link, you can use /files/list_folder and pass in a shared_link parameter.
/1/revisions	/2/files/list_revisions Note: Return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /revisions returned v1-style metadata. In v2, /files/list_revisions will return a list of v2-style metadata objects. See below on how to map the v1 return values to v2 metadata.
/1/search	/2/files/search Note: Return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /search returned v1-style metadata. In v2, /files/search will return a list of v2-style metadata objects. See below on how to map the v1 return values to v2 metadata. Tip: Did you know that for Dropbox Business accounts, API v2 now supports file-content search as well as file-name search? Upgrade your Business app to v2 to take advantage of this new functionality.

Uploading and downloading content

v1	v2
/1/files (GET)	/2/files/download
/1/files_put	/2/files/upload Note: Return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /files_put returned v1-style metadata. In v2, /files/upload will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata. Tip: The v1 parameter, overwrite, is now part of the v2 mode parameter, which lets you specify "overwrite," "add," or "update" for file conflicts.
/1/chunked_upload	/2/files/upload_session/start
/1/commit_chunked_upload	/2/files/upload_session/finish Tip: The v1 endpoint /commit_chunked_upload returned v1-style metadata. In v2, /files/upload_session/finish will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.
/1/media	/2/files/get_temporary_link Note: Parameters and return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /media returned v1-style metadata. In v2, /files/get_temporary_link will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.
/1/previews	/2/files/get_preview
/1/thumbnails	/2/files/get_thumbnail Note: Parameters and return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /thumbnails returned v1-style metadata. In v2, /files/get_thumbnail will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.

File operations

v1	v2
/1/copy_ref	/2/files/copy_reference/get Note: Return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /copy_ref returned v1-style metadata. In v2, /files/copy_reference/get will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.
/1/fileops/copy	/2/files/copy Note: Return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /fileops/copy returned v1-style metadata. In v2, /files/copy will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.
/1/fileops/create_folder	/2/files/create_folder Note: Return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /fileops/create_folder returned v1-style metadata. In v2, /files/create_folder will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.
/1/fileops/delete	/2/files/delete Note: Return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /fileops/delete returned v1-style metadata. In v2, /files/delete will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.
/1/fileops/move	/2/files/move Note: Return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /fileops/move returned v1-style metadata. In v2, /files/move will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.
/1/fileops/permanently_delete	/2/files/permanently_delete Note: Return values have changed. Please refer to the full documentation for details.
/1/restore	/2/files/restore Tip: The v1 endpoint /restore returned v1-style metadata. In v2, /files/restore will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.
/1/save_url	/2/files/save_url Note: Return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /save_url returned v1-style metadata. In v2, /files/save_url will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.
/1/save_url_job	/2/files/save_url/check_job_status Note: Return values have changed. Please refer to the full documentation for details. Tip: The v1 endpoint /save_url_job returned v1-style metadata. In v2, /files/save_url/check_job_status will return a v2-style metadata object. See below on how to map the v1 return values to v2 metadata.

Tip: Did you know that API v2 has tons of new sharing functionality, including the ability to invite users to shared folders? Learn more.

v1	v2
/1/shares	/2/sharing/create_shared_link_with_settings Note: Parameters and return values have changed. Please refer to the full documentation for details.
/1/shared_folders (no <shared_folder_id>)	/2/sharing/list_folders Note: Return values have changed slightly. Please see full documentation for details. Note: These results may be paginated. See /sharing/list_folders/continue for more details.
/1/shared_folders (with <shared_folder_id>)	/2/sharing/get_folder_metadata Note: Return values have changed slightly. Please see full documentation for details.

Working with teams (a.k.a. API v1's "Dropbox for Business API")

Note: For apps with Team Member File Access permissions, the custom HTTP header has changed. For v1 calls, you used X-Dropbox-Perform-As-Team-Member. For v2 calls, you will use Dropbox-API-Select-User.

Tip: Did you know that API v2 for Business teams now supports listing all the apps that members have linked to their Dropbox accounts? Check out the /2/team/linked_apps/ endpoints to learn more.

v1	v2
/1/team/get_info	/2/team/get_info
/1/team/members/list	/2/team/members/list Note: These results may be paginated. See /2/team/members/list/continue for more details.
/1/team/members/get_info	/2/team/members/get_info
/1/team/members/get_info_batch	Use /2/team/members/get_info and pass in a list of team_member_ids in the members parameter.
/1/team/members/add	/2/team/members/add Note: The v2 version can add up to 20 members at a time. If it returns async_job_id, use /2/team/members/add/job_status/get to check the status of the asynchronous additions of each team member.
/1/team/members/set_profile	/2/team/members/set_profile Note: Parameters and return values have changed. Please refer to the full documentation for details.
/1/team/members/set_permissions	/2/team/members/set_admin_permissions Note: Parameters and return values have changed. Please refer to the full documentation for details. Tip: There are now four levels of permission for team members. See the full documentation for details.
/1/team/members/send_welcome_email	/2/team/members/send_welcome_email Note: Parameters have changed. Please refer to the full documentation for details.
/1/team/members/remove	/2/team/members/remove Note: Parameters have changed. Please refer to the full documentation for details. Note: This endpoint may initiate an asynchronous job. If it returns an async_job_id, use /2/team/members/remove/job_status/get to check the status. Tip: You can now also suspend users, which preserves their data but blocks them from accessing their account. See /2/team/members/suspend and /2/team/members/unsuspend for more details.
/1/team/groups/list	/2/team/groups/list Note: Parameters and return values have changed. Please refer to the full documentation for details. Note: These results may be paginated. See /2/team/groups/list/continue for more details.
/1/team/groups/get_info	/2/team/groups/get_info Note: Parameters and return values have changed. Please refer to the full documentation for details.
/1/team/groups/create	/2/team/groups/create Note: Parameters and return values have changed. Please refer to the full documentation for details.
/1/team/groups/delete	/2/team/groups/delete Note: Parameters and return values have changed. Please refer to the full documentation for details. Note: This endpoint may initiate an asynchronous job. If it returns an async_job_id, use /2/team/groups/job_status/get to check the status.
/1/team/groups/members/add	/2/team/groups/members/add Note: Parameters and return values have changed. Please refer to the full documentation for details. Note: This endpoint may initiate an asynchronous job. If it returns an async_job_id, use /2/team/groups/job_status/get to check the status.
/1/team/groups/members/remove	/2/team/groups/members/remove Note: Parameters and return values have changed. Please refer to the full documentation for details. Note: This endpoint may initiate an asynchronous job. If it returns an async_job_id, use /2/team/groups/job_status/get to check the status.
/1/team/groups/members/set_access_type	/2/team/groups/members/set_access_type Note: Parameters and return values have changed. Please refer to the full documentation for details.
/1/team/reports/get_storage	/2/team/reports/get_storage
/1/team/reports/get_activity	/2/team/reports/get_activity
/1/team/reports/get_membership	/2/team/reports/get_membership
/1/team/reports/get_devices	/2/team/reports/get_devices
/1/team/log/get_events	/2/team_log/get_events Note: The get_events API has significant changes and improvements in V2; see the events migration guide for more details.

Note: Many v2 team endpoints now trigger asynchronous processes on the server (e.g. /team/members/add). When that is the case, the API call will return an async_job_id. When making calls to potentially asynchronous endpoints, check for the async_job_id field; if it's present, use that string to call the relevant /job_status/get endpoint (e.g. /team/members/add/job_status/get) until it returns complete. Once complete, you can call the relevant endpoint(s) (e.g. /team/members/get_info) to get the metadata you need.

Metadata responses: v1 → v2 mapping

In v1, calls to /commit_chunked_upload, /delta, /fileops/copy, /fileops/create_folder, /fileops/delete, /fileops/move, /files_put, /media, /metadata, /metadata/link, /restore, /revisions, /search, and /thumbnails would return the content metadata as a JSON object. The v1 response included various fields that described properties of a file or folder. In v2, you will use the equivalent fields in the FileMetadata, FolderMetadata, and DeletedMetadata objects. With the HTTP API, these are in JSON format; in the SDKs, they're returned as language-specific objects.

v1	v2
size	Not available
bytes	size
path	path_display
is_dir	Check if .tag = "folder"
is_deleted	Check if .tag = "deleted" (only included if deleted folders and files are being returned)
rev	rev (returned for FileMetadata only)
hash	Not available; Use /2/files/list_folder to stay up to date on the contents of a folder.
thumb_exists	Check if the the file has one of the following file extensions: jpg, jpeg, png, tiff, tif, gif or bmp, and if it's less than 20MB in size; if so, use /2/files/get_thumbnail.
photo_info	Use media_info/metadata, and check if .tag = "photo." Only returned when the include_media_info parameter is true.
video_info	Use media_info/metadata, and check if .tag = "video." Only returned when the include_media_info parameter is true.
icon	Not available
modified	server_modified (Note: date formats have changed)
client_mtime	client_modified (Note: date formats have changed)
root	Not available
shared_folder	Use shared_folder_id for the ID, and the data in the /sharing_info object for more information about the owner, membership, and groups.
read_only	sharing_info/read_only
parent_shared_folder_id	sharing_info/parent_shared_folder_id
modifier	sharing_info/modified_by
mime_type	Not available

Authentication: Migrating access tokens and permissions

Does your app use OAuth 1 access tokens? If so, you'll have to migrate them to OAuth 2 tokens. Use the /2/auth/token/from_oauth1 endpoint to migrate an OAuth 1 token to an OAuth 2 token. If not, then your app only uses OAuth 2 tokens, and if it also has Full Dropbox or App Folder access, then those tokens will work for API v2 calls.

See this guide for more on how to use OAuth 2 with Dropbox.

Full Dropbox and App Folder permission apps

If your app has either App Folder or Full Dropbox permission, you will be able to use the same app key(s) in v2. You will need to migrate your OAuth 1 tokens (see above), if you have any.

If you're using the Sync SDK, see this guide on how to migrate stored OAuth tokens. (Note that this guide was written for migrating to Core API v1; you should follow the instructions on getting the stored tokens from the Sync SDK, but install an API v2 SDK instead of a v1 Core API SDK.)

File Type permission apps

If your app has File Type permission, you will need to re-authenticate your users with a new permission, or "access type." File Type permission is not supported in API v2.

First, create a new app in the Dropbox App Console. Select either App Folder or Full Dropbox as the access type.

Then, implement a re-authentication flow for your users; it can probably be similar to your original authentication flow where you asked users to link their Dropbox account in the first place. Using the app key and secret from your new app, follow the OAuth guide to prompt your users to link their Dropbox accounts from the new app. If you're using the SDKs, they'll take care of some of the OAuth 2 process automatically.

Tip: When messaging to your users the need to re-link their Dropbox account, we suggest the following language: "The Dropbox integration has changed. Please re-link your account to continue [syncing/backing up data/accessing files/etc]."

Finally, you can filter for specific file types in your app, using the same file extensions as Dropbox API v1.

Team permission apps

All team-permission apps can re-use their OAuth 2 access tokens to make calls to API v2 on behalf of a team admin. You will need to migrate your OAuth 1 tokens (see above), if you have any.

Error handling

The errors reported back from the API have changed in v2. In v1, we mapped every endpoint-specific error to an HTTP status code. In v2, all endpoint-specific errors are returned with a 409 status code; the details of the error are in the response body.

Example

In v1, if you used the /1/fileops/copy endpoint to copy a file or folder into a read-only folder, the API would return HTTP status code 403, which is documented as: "An invalid copy operation was attempted (e.g. there is already a file at the given destination, or trying to copy a shared folder)."

In v2, attempting the same operation with the /2/files/copy endpoint will return HTTP status code 409, with with a stable and documented error identifier in the body:

{
  "error_summary": "to/no_write_permission/..",
  "error": {
    ".tag": "to",
    "to": {
      ".tag": "no_write_permission"
    }
  }
}

As you can see, this is a nested error. It is a to error, which is a WriteError datatype; the value of the first .tag field tells you what the sub-datatype is. The specific error is a no_write_permission error, which is documented as, "The user doesn't have permissions to write to the target location."

In API v2, .tag values in error objects will tell you the specific type of error. (Learn more about .tag fields here.) The error_summary value is the full error, with datatype and sub-datatypes. The error object contains the details, like .tag and the specific error types.

To handle errors in v2, refer to the full documentation of each endpoint to see which error types may be returned. You can special-case failure modes for specific error types (for example, if the error is the no_write_permission, you can tell the user to choose a different folder.) You can also fail gracefully on other errors (for example, if the app is trying to get thumbnails but a non-LookupError error is returned, the app could just show a placeholder thumbnail in the UI).

If it makes sense in your app's user experience, and if it's set in the error object, you can utilize the user_message value as a human-readable error message.

More on errors

For more information on how the error status codes work in v2, read the "Errors" sections in the v2 documentation. You can also read this blog post for more background on how API v2 uses HTTP status codes.

Syntax comparison for v1 and v2: Examples in HTTP

API v2 utilizes HTTP a bit differently than v1. Using curl, here are some examples of how you would use v1 and v2 to see the contents of a folder, or download a file.

Note that all v2 endpoints use POST, and that the parameters generally sent as JSON objects in the request body. See the "Request and response formats" section of the full HTTP documentation for more info.

Example: Get the metadata of a folder

v1

curl -X GET https://api.dropboxapi.com/1/metadata/auto/Projects?list=false \
--header "Authorization: Bearer <user token>"

v2

curl -X POST https://api.dropboxapi.com/2/files/get_metadata \
--header "Authorization: Bearer <user token>" \
--header "Content-Type: application/json" \
--data "{\"path\": \"/Projects\"}"

Example: Download a file

v1

curl -X GET https://content.dropboxapi.com/1/files/auto/Projects/tmp.png \
--header "Authorization: Bearer <user token>

v2

curl -X POST https://content.dropboxapi.com/2/files/download \
--header "Authorization: Bearer <user token>"
--header "Dropbox-API-Arg: {\"path\": \"/Projects/tmp.png\"}"

Syntax comparison for v1 and v2: Examples for SDKs

The syntax has also changed in our v2 SDKs. Here's how you would upload a file in a few different languages, using v1 and v2.

Python

v1

response = client.put_file('/magnum-opus.txt', f)

v2

file_metadata = dbx.files_upload(f, '/magnum-opus.txt')

Java

v1

DbxEntry.File uploadedFile = client.uploadFile("/magnum-opus.txt",
        DbxWriteMode.add(), inputFile.length(), inputStream);

v2

FileMetadata metadata = client.files().uploadBuilder("/magnum-opus.txt")
        .uploadAndFinish(in);

Android

v1

Entry response = mDBApi.putFile("/magnum-opus.txt", inputStream,
                                file.length(), null, null);

v2

FileMetadata metadata = client.files().uploadBuilder("/magnum-opus.txt")
        .uploadAndFinish(in);

iOS

v1 (Objective-C)

[self.restClient uploadFile:filename toPath:destDir withParentRev:nil fromPath:localPath];

v2 (Swift)

client.files.upload(path: "/magnum-opus.txt", body: fileData!)

Note: We also have an official API v2 SDK for Objective-C.

Miscellaneous: Important fields, format changes, and more

Date formats

v1: All dates in the API are strings in the following format: "Sat, 21 Aug 2010 22:31:20 +0000"
v2: All dates are strings in the ISO 8601 "combined date and time representation" format. For example, "2007-04-05T14:30".

Drop-ins:

Chooser and Saver apps do not need to be migrated to v2; they will continue working after v1 is retired.

locale

v1: All endpoints took a locale parameter
v2: All endpoints can take the new "Dropbox-Locale: <locale>" header

.tag fields in JSON objects

The HTTP API returns JSON objects that have a .tag field. This is a special informational field that indicates which value is returned; for example, you can look at the .tag value of a metadata object to see if it's for a file or a folder, or you can look at the .tag value of an error object to see what kind of error it is.
The SDKs take care of reading and interpreting the .tag value for you.

Root path

v1: "/"" (forward slash)
v2: "" (empty string)

API v1 retirement

API v1 is retired as of September 2017. Any API v1 calls will fail with a 400 error with the body:

{"error": "v1_retired"}