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.

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:

2015-05-15T15:50:38Z

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

Case insensitivity

Like Dropbox itself, the Dropbox API is 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 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 components, it can get it from the Metadata.name or last path component of each relevant Metadata.path_display entry.

Authorization

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.

/oauth2/authorize

Description

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.

If the user isn't already signed in to the Dropbox web site, they will be prompted to do so on this web page. Note that some users use their Google account to sign in to Dropbox. In order to comply with Google's policy against processing the OAuth flow inside a web-view, you should not display this web page inside a web-view.

URL Structure
https://www.dropbox.com/oauth2/authorize

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.

Method
GET
Parameters
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 4.4.1.8 and 4.4.2.5 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.
Returns

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

[REDIRECT_URI]?code=ABCDEFG&state=[STATE]

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

[REDIRECT_URI]#access_token=ABCDEFG&token_type=bearer&account_id=dbid%3AAAH4f99T0taONIb-OurWxbNQ6ywGRopQngc&uid=12345&state=[STATE]
Errors

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

/oauth2/token

Description

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
https://api.dropboxapi.com/oauth2/token
Method
POST
Parameters
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.
Returns

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

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

CodeDescription
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: 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.
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.
RateLimitError
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.
KeyDescription
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. While this provides a human-readable error string, "error_summary" should not be used for programmatic error handling. To disincentive this, 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.

paper

This namespace contains endpoints and data types for managing docs and folders in Dropbox Paper.

/docs/get_metadata

Version
PREVIEW - may change or disappear without notice
Description

Returns Paper doc metadata.

URL Structure
https://api.dropboxapi.com/2/paper/docs/get_metadata
Authentication
User Authentication
Endpoint format
RPC
Example
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\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
RefPaperDoc
doc_id String The Paper doc ID.
Returns
{
    "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"
}
PaperDocGetMetadataResult
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.
Errors
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.
doc_not_found Void The required doc was not found.

/docs/search/continue

Version
PREVIEW - may change or disappear without notice
Description

Returns a list of Paper docs that match the query string. Starts from the given cursor.

URL Structure
https://api.dropboxapi.com/2/paper/docs/search/continue
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/search/continue \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"cursor\": \"dn2oicjwd89m4lgkve098wencdn2\"}"
Parameters
{
    "cursor": "dn2oicjwd89m4lgkve098wencdn2"
}
PaperDocSearchContinueArgs
cursor String The cursor obtained from docs/search or docs/search/continue. Allows for pagination.
Returns
{
    "docs": [
        {
            "doc_id": "ckwpocm928fnciwcdmo2i",
            "title": "Paper is awesome!",
            "snippets": [
                "\u003cb class=\"hit\"\u003ekeyword\u003c/b\u003e"
            ],
            "created_date": "2017-05-10T07:07:03Z",
            "last_edited_date": "2017-05-11T08:20:46Z",
            "creator_name": "Dropbox Panda",
            "last_editor_name": "Dropbox Panda"
        }
    ],
    "total_matches": 37,
    "has_more": true,
    "cursor": "dn2oicjwd89m4lgkve098wencdn2"
}
PaperDocSearchResults
docs List of (PaperDocSearchResultMeta) A list of Paper docs that match the query string.
PaperDocSearchResultMeta
doc_id String The Paper doc ID.
title String The Paper doc title.
snippets List of (String) The snippets of this Paper doc that contain the query string. It will be a list of HTML strings and the matches will be keyword.
created_date Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The date that this Paper doc was created.
last_edited_date Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The date that this Paper doc was last edited.
creator_name String? The name of the person who created this Paper doc. This field is optional.
last_editor_name String? The name of the person who last edited this Paper doc. This field is optional.
total_matches Int32 Total number of Paper docs that match this query string.
has_more Boolean True if there are some more matched results that are not returned.
cursor String? Pass this cursor into docs/search/continue to paginate through all users. This field is optional.
Errors
Example: expired_cursor
{
    "error_summary": "expired_cursor/...",
    "error": {
        ".tag": "expired_cursor"
    }
}
Example: invalid_cursor
{
    "error_summary": "invalid_cursor/...",
    "error": {
        ".tag": "invalid_cursor"
    }
}
Example: wrong_user_in_cursor
{
    "error_summary": "wrong_user_in_cursor/...",
    "error": {
        ".tag": "wrong_user_in_cursor"
    }
}
Example: reset
{
    "error_summary": "reset/...",
    "error": {
        ".tag": "reset"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
PaperApiCursorError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
expired_cursor Void The provided cursor is expired.
invalid_cursor Void The provided cursor is invalid.
wrong_user_in_cursor Void The provided cursor contains invalid user.
reset Void Indicates that the cursor has been invalidated. Call the corresponding non-continue endpoint to obtain a new cursor.

deprecated

All deprecated endpoints, across namespaces