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.

If you want your app's Dropbox integration to continue working after API v1 is retired, you must fully migrate it to API v2. We will aim to give developers ample time to migrate and test the new integrations. Additionally, any new functionality added to the Dropbox platform will only be added 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.
  • If there's functionality missing in v2, update what you can, and support the rest with a hybrid integration. Also, please file a support ticket with us about the missing functionality, so we can keep track of feature requests.
  • 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.

v1v2
/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.

v1v2
/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:

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

v1v2
/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.

/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

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

v1v2
/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.

Sharing

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

v1v2
/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.

v1v2
/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 Not yet available. For now, use /1/team/log/get_events. We will update this guide when the v2 version of this endpoint is available.

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.

v1v2
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. See the v1 developer guide for a full list of file extensions per file-type.

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 info on how the error status codes have changed between v1 and v2, read the sections on "Error handling" in the v1 documentation and 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 are currently working on an official API v2 SDK for Objective-C.

Hybrid mode

You can use both API v1 and v2 at the same time in an app. This works for the HTTP API, the Java SDK, and the Python SDK.

To do this with the HTTP API, you can just make regular API v1 calls with the appropriate URL structure and method. The SDKs mentioned above have the v1 functionality built-in. For both Java and Python, just follow the v1 tutorials to create a client and use it to make v1 calls.

Miscellaneous: Important fields, format changes, and more

Date formats

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

In June 2016, we announced the deprecation timeline for API v1. When API v1 is retired in June 2017, any further API v1 calls will fail with a 400 error with the body:

{"error": "v1_retired"}

Further reading

To learn more about the new design of the HTTP endpoints, including the RPC endpoints, content uploading and downloading, and other accepted URL parameters, read the beginning of the full HTTP documentation.

For more on the philosophy behind API v2, read the blog post "A preview of the new Dropbox API v2."

Finally, if you're curious about API v2's new use of HTTP status codes, you can read the blog post, "How many HTTP status codes should your API use?"