Dropbox API v2

The Dropbox API allows developers to work with files in Dropbox, including advanced functionality like full-text search, thumbnails, and sharing. The Dropbox API explorer is the easiest way to get started making API calls.

Request and response formats

In general, the Dropbox API uses HTTP POST requests with JSON arguments and JSON responses. Request authentication is via OAuth 2.0 using the Authorization request header or authorization URL parameter.

The .tag field in an object identifies the subtype of a struct or selected member of a union.

When specifying a Void member of a union, you may supply just the member string in place of the entire tagged union object. For example, when supplying a WriteMode, you can supply just "mode": "add" instead of "mode": {".tag": "add"}}. This shorthand is not allowed for non-Void members. For example, the following is not allowed for a WriteMode, as update is not a Void member: "mode": "update".

RPC endpoints

These endpoints accept arguments as JSON in the request body and return results as JSON in the response body. RPC endpoints are on the api.dropboxapi.com domain.

Content-upload endpoints

These endpoints accept file content in the request body, so their arguments are instead passed as JSON in the Dropbox-API-Arg request header or arg URL parameter. These endpoints are on the content.dropboxapi.com domain.

Content-download endpoints

As with content-upload endpoints, arguments are passed in the Dropbox-API-Arg request header or arg URL parameter. The response body contains file content, so the result will appear as JSON in the Dropbox-API-Result response header. These endpoints are also on the content.dropboxapi.com domain.

These endpoints also support HTTP GET along with ETag-based caching (If-None-Match) and HTTP range requests.

For information on how to properly encode the JSON, see the JSON encoding page.

Browser-based JavaScript and CORS pre-flight requests

When browser-based JavaScript code makes a cross-site HTTP request, the browser must sometimes send a "pre-flight" check to make sure the server allows cross-site requests. You can avoid the extra round-trip by ensuring your request meets the CORS definition of a "simple cross-site request".

  • Use URL parameters arg and authorization instead of HTTP headers Dropbox-API-Arg and Authorization.
  • Set the Content-Type to "text/plain; charset=dropbox-cors-hack" instead of "application/json" or "application/octet-stream".
  • Always set the URL parameter reject_cors_preflight=true. This makes it easier to catch cases where your code is unintentionally triggering a pre-flight check.

Date format

All dates in the API use UTC and are strings in the ISO 8601 "combined date and time representation" format:


Path formats

Paths are relative to an application's root (either an app folder or the root of a user's Dropbox, depending on the app's access type). The empty string ("") represents the root folder. All other paths must start with a slash (e.g. "/hello/world.txt"). Paths may not end with a slash or whitespace. For other path restrictions, refer to the help center.

Every file and folder in Dropbox also has an ID (e.g. "id:abc123xyz") that can be obtained from any endpoint that returns metadata. These IDs are case-sensitive, so they should always be stored with their case preserved, and always compared in a case-sensitive manner. Some endpoints, as noted in the individual endpoint documentation below, can accept IDs in addition to normal paths. A path relative to a folder's ID can be constructed by using a slash (e.g. "id:abc123xyz/hello.txt").

For endpoints that accept performing actions on behalf of a team administrator using the Dropbox-API-Select-Admin header, files may be referenced using a namespace-relative path (e.g. "ns:123456/cupcake.png"). In this case, the namespace ID, "123456", would be the shared_folder_id or team_folder_id of the shared folder or the team folder containing the file or folder, and the path, "/cupcake.png", would be the logical path to the content relative to its shared folder or team folder container.

Path case insensitivity

Like in Dropbox itself, paths in the Dropbox API are case-insensitive, meaning that /A/B/c.txt is the same file as /a/b/C.txt and is the same file as /a/B/c.txt.

This can cause problems for apps that store file metadata from users in case-sensitive databases (such as SQLite or Postgres). Case insensitive collations should be used when storing Dropbox path metadata in such databases. Alternatively, developers need to make sure their query operators are explicitly case insensitive.

Also, while Dropbox is case-insensitive, it makes efforts to be case-preserving. Metadata.name will contain the correct case. Metadata.path_display usually will contain the correct case, but sometimes only in the last path component. If your app needs the correct case for all path components, it can get it from the Metadata.name or last path component of each relevant Metadata.path_display entry.


Dropbox supports OAuth 2.0 for authorizing API requests. Find out more in our OAuth guide. Authorized requests to the API should use an Authorization header with the value Bearer <TOKEN>, where <TOKEN> is an access token obtained through the OAuth flow.

Note: OAuth is an authorization protocol, not an authentication protocol. Dropbox should not be used as an identity provider.



This starts the OAuth 2.0 authorization flow. This isn't an API call—it's the web page that lets the user sign in to Dropbox and authorize your app. After the user decides whether or not to authorize your app, they will be redirected to the URI specified by redirect_uri.

OAuth 2.0 supports two authorization flows:

  • The code flow returns a code via the redirect_uri callback which should then be converted into a bearer token using the /oauth2/token call. This is the recommended flow for apps that are running on a server.
  • The token or implicit grant flow returns the bearer token via the redirect_uri callback, rather than requiring your app to make a second call to a server. This is useful for pure client-side apps, such as mobile apps or JavaScript-based apps.

For more information on the two flows, see Section 1.3 of the OAuth 2 spec.

Your app should send the user to this app authorization page in their system browser. If the user isn't already signed in to the Dropbox website, they will be prompted to do so on this web page. This web page should not be displayed in a web-view. This is in order to maintain compatibilty with the website and to comply with Google's policy against processing their OAuth flow inside a web-view, to support users who sign in to Dropbox using their Google accounts. Learn about the dropbox.com system requirements.

URL Structure

Note: This is the only step that requires an endpoint on www.dropbox.com. All other API requests are done via api.dropboxapi.com, content.dropboxapi.com, or notify.dropboxapi.com.

response_type String The grant type requested, either token or code.
client_id String The app's key, found in the App Console.
redirect_uri String? Where to redirect the user after authorization has completed. This must be the exact URI registered in the App Console; even 'localhost' must be listed if it is used for testing. All redirect URIs must be HTTPS except for localhost URIs. A redirect URI is required for the token flow, but optional for the code flow. If the redirect URI is omitted, the code will be presented directly to the user and they will be invited to enter the information in your app.
state String? Up to 500 bytes of arbitrary data that will be passed back to your redirect URI. This parameter should be used to protect against cross-site request forgery (CSRF). See Sections and of the OAuth 2.0 threat model spec.
require_role String? If this parameter is specified, the user will be asked to authorize with a particular type of Dropbox account, either work for a team account or personal for a personal account. Your app should still verify the type of Dropbox account after authorization since the user could modify or remove the require_role parameter.
force_reapprove Boolean? Whether or not to force the user to approve the app again if they've already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If true, the user will not be automatically redirected and will have to approve the app again.
disable_signup Boolean? When true (default is false) users will not be able to sign up for a Dropbox account via the authorization page. Instead, the authorization page will show a link to the Dropbox iOS app in the App Store. This is only intended for use when necessary for compliance with App Store policies.
locale String? If the locale specified is a supported language, Dropbox will direct users to a translated version of the authorization website. Locale tags should be IETF language tags.
force_reauthentication Boolean? When true (default is false) users will be signed out if they are currently signed in. This will make sure the user is brought to a page where they can create a new account or sign in to another account. This should only be used when there is a definite reason to believe that the user needs to sign in to a new or different account.

Because /oauth2/authorize is a website, there is no direct return value. However, after the user authorizes your app, they will be sent to your redirect URI. The type of response varies based on the response_type.

Code flow

These parameters are passed in the query string (after the ? in the URL):

code String The authorization code, which can be used to attain a bearer token by calling /oauth2/token.
state String The state content, if any, originally passed to /oauth2/authorize.

Sample response


Token flow

These parameters are passed in the URL fragment (after the # in the URL).

Note: as fragments, these parameters can be modified by the user and must not be trusted server-side. If any of these fields are being used server-side, please consider using the Code flow, or alternatively using the fields returned from /get_current_account instead.

access_token String A token which can be used to make calls to the Dropbox API.
token_type String The type of token, which will always be bearer.
account_id String A user's account identifier used by API v2.
team_id String A team's identifier used by API v2.
uid String Deprecated. The API v1 user/team identifier. Please use account_id instead, or if using the Dropbox Business API, team_id.
state String The state content, if any, originally passed to /oauth2/authorize.

Sample response


In either flow, if an error occurs, including if the user has chosen not to authorize the app, the following parameters will be included in the redirect URI:

error String An error code per Section of the OAuth 2.0 spec.
error_description String A user-friendly description of the error that occurred.
state String The state content, if any, originally passed to /oauth2/authorize.



This endpoint only applies to apps using the authorization code flow. An app calls this endpoint to acquire a bearer token once the user has authorized the app.

Calls to /oauth2/token need to be authenticated using the apps's key and secret. These can either be passed as application/x-www-form-urlencoded POST parameters (see parameters below) or via HTTP basic authentication. If basic authentication is used, the app key should be provided as the username, and the app secret should be provided as the password.

URL Structure
curl https://api.dropbox.com/oauth2/token \
    -d code=<AUTHORIZATION_CODE> \
    -d grant_type=authorization_code \
    -d redirect_uri=<REDIRECT_URI> \
code String The code acquired by directing users to /oauth2/authorize?response_type=code.
grant_type String The grant type, which must be authorization_code.
client_id String? If credentials are passed in POST parameters, this parameter should be present and should be the app's key (found in the App Console).
client_secret String? If credentials are passed in POST parameters, this parameter should be present and should be the app's secret.
redirect_uri String? Only used to validate that it matches the original /oauth2/authorize, not used to redirect again.

A JSON-encoded dictionary including an access token (access_token), token type (token_type), an API v2 user ID (account_id), or if team-linked, an API v2 team ID (team_id) instead. The API v1 identifier value (uid) is deprecated and should no longer be used. The token type will always be "bearer".

Sample response

{"access_token": "ABCDEFG", "token_type": "bearer", "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc", "uid": "12345"}


Errors are returned using standard HTTP error code syntax. Depending on the status code, the response body may be in JSON or plaintext.

Errors by status code

400Bad input parameter. The response body is a plaintext message with more information.
401Bad or expired token. This can happen if the access token is expired or if the access token has been revoked by Dropbox or the user. To fix this, you should re-authenticate the user.
The Content-Type of the response is JSON of typeAuthError
Example: invalid_access_token
    "error_summary": "invalid_access_token/...",
    "error": {
        ".tag": "invalid_access_token"
Example: invalid_select_user
    "error_summary": "invalid_select_user/...",
    "error": {
        ".tag": "invalid_select_user"
Example: invalid_select_admin
    "error_summary": "invalid_select_admin/...",
    "error": {
        ".tag": "invalid_select_admin"
Example: user_suspended
    "error_summary": "user_suspended/...",
    "error": {
        ".tag": "user_suspended"
Example: expired_access_token
    "error_summary": "expired_access_token/...",
    "error": {
        ".tag": "expired_access_token"
Example: route_access_denied
    "error_summary": "route_access_denied/...",
    "error": {
        ".tag": "route_access_denied"
Example: no_team_api_access
    "error_summary": "no_team_api_access/...",
    "error": {
        ".tag": "no_team_api_access"
Example: invalid_team_auth_header
    "error_summary": "invalid_team_auth_header/...",
    "error": {
        ".tag": "invalid_team_auth_header"
Example: federation_access_denied
    "error_summary": "federation_access_denied/...",
    "error": {
        ".tag": "federation_access_denied"
Example: other
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
AuthError (open union)
Errors occurred during authentication. This datatype comes from an imported namespace originally defined in the auth namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_access_token Void The access token is invalid.
invalid_select_user Void The user specified in 'Dropbox-API-Select-User' is no longer on the team.
invalid_select_admin Void The user specified in 'Dropbox-API-Select-Admin' is not a Dropbox Business team admin.
user_suspended Void The user has been suspended.
expired_access_token Void The access token has expired.
missing_scope TokenScopeError The access token does not have the required scope to access the route.
This datatype comes from an imported namespace originally defined in the auth namespace.
required_scope String The required scope to access the route.
route_access_denied Void The route is not available to public.
no_team_api_access Void The user doesn't have access to team endpoints.
invalid_team_auth_header Void The values sent in the team auth header are not a valid combination.
federation_access_denied Void The user is not a federation admin or the requested team is not part of that user's federation.
403The user or team account doesn't have access to the endpoint or feature.
The Content-Type of the response is JSON of typeAccessError
AccessError (open union)
Error occurred because the account doesn't have permission to access the resource. This datatype comes from an imported namespace originally defined in the auth namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_account_type InvalidAccountTypeError Current account type cannot access the resource.
InvalidAccountTypeError (open union)
This datatype comes from an imported namespace originally defined in the auth namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
endpoint Void Current account type doesn't have permission to access this route endpoint.
feature Void Current account type doesn't have permission to access this feature.
paper_access_denied PaperAccessError Current account cannot access Paper.
PaperAccessError (open union)
This datatype comes from an imported namespace originally defined in the auth namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
paper_disabled Void Paper is disabled.
not_paper_user Void The provided user has not used Paper yet.
409Endpoint-specific error. Look to the JSON response body for the specifics of the error.
429Your app is making too many requests for the given user or team and is being rate limited. Your app should wait for the number of seconds specified in the "Retry-After" response header before trying again.
The Content-Type of the response can be JSON or plaintext. If it is JSON, it will be typeRateLimitErrorYou can find more information in the data ingress guide.
Error occurred because the app is being rate limited. This datatype comes from an imported namespace originally defined in the auth namespace.
reason RateLimitReason The reason why the app is being rate limited.
RateLimitReason (open union)
This datatype comes from an imported namespace originally defined in the auth namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
too_many_requests Void You are making too many requests in the past few minutes.
too_many_write_operations Void There are currently too many write operations happening in the user's Dropbox.
retry_after UInt64 The number of seconds that the app should wait before making another request. The default for this field is 1.
5xxAn error occurred on the Dropbox servers. Check status.dropbox.com for announcements about Dropbox service issues.

Endpoint-specific errors (409)

The following table describes the top-level JSON object attributes present in the body of 409 responses.
errorA value that conforms to the error data type schema defined in the definition of each route.
error_summaryA string that summarizes the value of the "error" key. It is a concatenation of the hierarchy of union tags that make up the error. This provides a human-readable error string, and can also be used for simple programmatic error handling via prefix matching. To disincentivize exact string matching, we append a random number of "." characters at the end of the string.
user_messageAn optional field. If present, it includes a message that can be shown directly to the end user of your app. You should show this message if your app is unprepared to programmatically handle the error returned by an endpoint.

Generate access token

Use the dropdown to select which app to make API calls with. An access token for the chosen app will be generated and inserted into the examples below.

By generating an access token, you will be able to make API calls for your own account without going through the authorization flow. To obtain access tokens for other users, use the standard OAuth flow.


This namespace contains endpoints and data types for managing docs and folders in Dropbox Paper.
New Paper users will see docs they create in their filesystem as '.paper' files alongside their other Dropbox content. The /paper endpoints are being deprecated and you'll need to use /files and /sharing endpoints to interact with their Paper content. Read more in the Paper Migration Guide.


PREVIEW - may change or disappear without notice

Returns Paper doc metadata.

This endpoint does not support apps with the app folder permission.

URL Structure
User Authentication
Endpoint format
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/get_metadata \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\"}"
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
doc_id String The Paper doc ID.
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "owner": "steph@example.com",
    "title": "Onbaording Doc",
    "created_date": "2016-01-20T00:00:00Z",
    "status": {
        ".tag": "active"
    "revision": 56556,
    "last_updated_date": "2017-01-02T00:00:00Z",
    "last_editor": "stephen@example.com"
doc_id String The Paper doc ID.
owner String The Paper doc owner's email address.
title String The Paper doc title.
created_date Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The Paper doc creation date.
status PaperDocStatus The Paper doc status.
PaperDocStatus (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
active Void The Paper doc is active.
deleted Void The Paper doc is deleted.
revision Int64 The Paper doc revision. Simply an ever increasing number.
last_updated_date Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The date when the Paper doc was last edited.
last_editor String The email address of the last editor of the Paper doc.
Example: insufficient_permissions
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
Example: other
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
Example: doc_not_found
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action. This may be due to it only having access to Paper as files in the Dropbox filesystem. For more information, refer to the Paper Migration Guide.
doc_not_found Void The required doc was not found.


All deprecated endpoints, across namespaces