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.
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".
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.
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.
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.
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".
arg and authorization instead of HTTP headers Dropbox-API-Arg and Authorization.Content-Type to "text/plain; charset=dropbox-cors-hack" instead of "application/json" or "application/octet-stream".reject_cors_preflight=true. This makes it easier to catch cases where your code is unintentionally triggering a pre-flight check.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
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.
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.
This API will evolve. Future updates of this API may add new endpoints, parameters, or fields. In order to keep older clients working, the behavior and return values of APIs with given parameter values will not change without advance notice, with two important exceptions: currently undocumented request parameters (whether they are actually ignored or not) may be given a specific meaning, and objects returned in responses may contain additional fields in the future.
Thus, clients that want to be future-proof should avoid passing undocumented parameters (as they may cause different behavior in the future), and they should avoid strict checks on the set of fields in objects found in responses.
For example, you should not consider a Metadata object invalid if it contains additional fields besides those currently documented below.
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.
Access tokens provided by Dropbox should be treated as opaque. Applications must support variable token size with tokens capable of exceeding 1KB. Applications should not depend on details such as access token composition as Dropbox reserves the right to make changes to token contents.
Note: OAuth is an authorization protocol, not an authentication protocol. If you're looking to use Dropbox as an identity provider, check out the Dropbox OpenID Connect Guide.
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 three authorization flows:
code flow returns an authorization code via the optional redirect_uri callback which should then be converted into a bearer access token using the /oauth2/token call. This is the recommended flow for apps that are running on a server.PKCE flow is an extension of the code flow that uses dynamically generated codes instead of a secret to perform an OAuth exchange from public clients. The PKCE flow is a newer, more secure alternative to the token (implicit) flow. It is the recommended flow for client-side apps, such as mobile, desktop, or browser JavaScript apps.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, desktop, or browser JavaScript apps. For more information on the code and token flows, see Section 1.3 of the OAuth 2 spec. For more info on the PKCE extension, see RFC 7636
Your app should send the user to this app authorization page in their system browser, which will display the permissions being granted. 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 compatibility 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.
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.
Example: Auth URL for code flow
https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code
Example: Auth URL for code flow with offline token access type
https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&token_access_type=offline&response_type=code
Example: Auth URL for PKCE code flow
https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code&code_challenge=<CHALLENGE>&code_challenge_method=<METHOD>
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.scope String? This parameter allows your user to authorize a subset of the scopes selected in the App Console. Multiple scopes are separated by a space. If this parameter is omitted, the authorization page will request all scopes selected on the Permissions tab. Read about scopes in the OAuth Guide.include_granted_scopes String? This parameter is optional. If set to user, Dropbox will return the currently requested scopes as well as all previously granted user scopes for the user. If set to team , Dropbox will return the currently requested scopes as well as all previously granted team scopes for the team. The request will fail if this parameter is provided but not set to user or team, or if it is set to user but the scope contains team scope, or if it is set to team but the authorizing user is not a team admin. If not set, Dropbox will return only the scopes requested in the scope parameter.token_access_type String? If this parameter is set to offline, then the access token payload returned by a successful /oauth2/token call will contain a short-lived access_token and a long-lived refresh_token that can be used to request a new short-lived access token as long as a user's approval remains valid. If set to online then only a short-lived access_token will be returned. If omitted, this parameter defaults to online.state String? Up to 2000 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.code_challenge String?(min_length=43, max_length=128) Part of the PKCE flow, the challenge should be an SHA-256 (S256) encoded value of a string that will serve as the code_verifier of the corresponding /oauth2/token call. Can can also be set to plain (plain).code_challenge_method String? Defines the code challenge method. Can be set to S256 (recommended) or plain.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.prompt String? Specifies whether the user should be prompted for reauthentication or consent. If none the user will not be prompted with an authorization screen. This will cause an error if the user has not previously authorized the app. If login the user will be prompted to sign in again before authorizing the app. This is equivalent to force_reauthentication=true. If consent the user will always be prompted for authorization. This is equivalent to force_reapprove=true. Errors may occur if one of these parameters conflicts with another (for example: prompt=none&force_reapprove=true).max_age UInt64? Forces user session refresh if last login time is longer than time specified (seconds).display, preferred_locales, and acr_values are accepted for compatibility but are non-operational.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.
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]
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 use the PKCE 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. This should always be treated as opaque with no guarantees as to the size or composition of this token.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]
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.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.
https://api.dropboxapi.com/oauth2/token
Example: code flow access token request
curl https://api.dropbox.com/oauth2/token \ -d code=<AUTHORIZATION_CODE> \ -d grant_type=authorization_code \ -d redirect_uri=<REDIRECT_URI> \ -d client_id=<APP_KEY> \ -d client_secret=<APP_SECRET>
Example: refresh token request
curl https://api.dropbox.com/oauth2/token \ -d grant_type=refresh_token \ -d refresh_token=<REFRESH_TOKEN> \ -d client_id=<APP_KEY> \ -d client_secret=<APP_SECRET>
Example: PKCE code flow access token request
curl https://api.dropbox.com/oauth2/token \ -d code=<AUTHORIZATION_CODE> \ -d grant_type=authorization_code \ -d redirect_uri=<REDIRECT_URI> \ -d code_verifier=<VERIFICATION_CODE> \ -d client_id=<APP_KEY>
Example: PKCE refresh token request
curl https://api.dropbox.com/oauth2/token \ -d grant_type=refresh_token \ -d refresh_token=<REFRESH_TOKEN> \ -d client_id=<APP_KEY>
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 for completing a code flow or refresh_token for using a refresh token to get a new access token.refresh_token String? A unique, long-lived token that can be used to request new short-lived access tokens without direct interaction from a user in your app.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? The redirect URI used to receive the authorization code from /oauth2/authorize, if provided. Only used to validate it matches the redirect URI supplied to /oauth2/authorize for the current authorization code. It is not used to redirect again.code_verifier String?(min_length=43, max_length=128) The client-generated string used to verify the encrypted code_challenge used in the Authorization URL.scope String? Only allowed when grant_type=refresh_token, this parameter can be used to request a specific subset of the scopes originally granted for the supplied refresh token. Multiple scopes are separated by a space. If this parameter is omitted, the returned access token will include all of the scopes originally granted for the supplied refresh token.This endpoint returns a JSON-encoded dictionary including fields below:
access_token String The access token to be used to call the Dropbox API. This should always be treated as opaque with no guarantees as to the size or composition of this token.expires_in Integer The length of time in seconds that the access token will be valid for.token_type String Will always be bearer.scope String The permission set applied to the token.account_id String An API v2 account ID if this OAuth 2 flow is user-linked.team_id String An API v2 team ID if this OAuth 2 flow is team-linked.refresh_token String If the token_access_type was set to offline when calling /oauth2/authorize, then response will include a refresh token. This refresh token is long-lived and won't expire automatically. It can be stored and re-used multiple times.id_token String If the request includes OIDC scopes and is completed in the response_type=code flow, then the payload will include an id_token which is a JWT token.uid String The API v1 identifier value. It is deprecated and should no longer be used.Sample response
Example: short-lived token
{
"access_token": "sl.AbX9y6Fe3AuH5o66-gmJpR032jwAwQPIVVzWXZNkdzcYT02akC2de219dZi6gxYPVnYPrpvISRSf9lxKWJzYLjtMPH-d9fo_0gXex7X37VIvpty4-G8f4-WX45AcEPfRnJJDwzv-",
"expires_in": 14400,
"token_type": "bearer",
"scope": "account_info.read files.content.read files.content.write files.metadata.read",
"account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
"uid": "12345"
}Example: short-lived "offline" access token
{
"access_token": "sl.u.AbX9y6Fe3AuH5o66-gmJpR032jwAwQPIVVzWXZNkdzcYT02akC2de219dZi6gxYPVnYPrpvISRSf9lxKWJzYLjtMPH-d9fo_0gXex7X37VIvpty4-G8f4-WX45AcEPfRnJJDwzv-",
"expires_in": 14400,
"token_type": "bearer",
"scope": "account_info.read files.content.read files.content.write files.metadata.read",
"refresh_token": "nBiM85CZALsAAAAAAAAAAQXHBoNpNutK4ngsXHsqW4iGz9tisb3JyjGqikMJIYbd",
"account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
"uid": "12345"
}Example: legacy long-lived access token
{
"access_token": "7rBynGOob1cAAAAAAAAAAe72L3T6rQK5ImB5a06ijnwRG9IdeTxvsqdZNAIxq8pZ",
"token_type": "bearer",
"account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
"uid": "12345"
} Example: OIDC request
{
"access_token": "sl.AbX9y6Fe3AuH5o66-gmJpR032jwAwQPIVVzWXZNkdzcYT02akC2de219dZi6gxYPVnYPrpvISRSf9lxKWJzYLjtMPH-d9fo_0gXex7X37VIvpty4-G8f4-WX45AcEPfRnJJDwzv-",
"expires_in": 14400,
"token_type": "bearer",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkRUVXpsY3Nw",
"scope": "account_info.read files.content.read files.content.write files.metadata.read",
"account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
"uid": "12345"
}Use the refresh token to get a new access token. This request won't return a new refresh token since refresh tokens don't expire automatically and can be reused repeatedly.
access_token String The access token to be used to call the Dropbox API.expires_in Integer The length of time in seconds that the access token will be valid for.token_type String Will always be bearer.scope String? The permission set applied to the token. Only returned when the scope parameter was set.Example:
{
"access_token": "sl.u.AbX9y6Fe3AuH5o66-gmJpR032jwAwQPIVVzWXZNkdzcYT02akC2de219dZi6gxYPVnYPrpvISRSf9lxKWJzYLjtMPH-d9fo_0gXex7X37VIvpty4-G8f4-WX45AcEPfRnJJDwzv-",
"expires_in": 14400,
"token_type": "bearer"
}Errors are returned using standard HTTP error code syntax. Depending on the status code, the response body may be in JSON or plaintext.
| Code | Description |
|---|---|
| 400 | Bad input parameter. The response body is a plaintext message with more information. |
| 401 | Bad 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. Note: Access tokens that are not returned exactly as provisioned will return this error. Be sure not to truncate or otherwise malform access tokens provided by Dropbox.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.TokenScopeError 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. |
| 403 | The 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.no_permission NoPermissionError Caller does not have permission to access the resource.NoPermissionError (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.unauthorized_account_id_usage UnauthorizedAccountIdUsageError Current caller does not have permission to access the account information for one or more of the specified account IDs.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. |
| 409 | Endpoint-specific error. Look to the JSON response body for the specifics of the error. |
| 429 | Your 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. |
| 5xx | An error occurred on the Dropbox servers. Check status.dropbox.com for announcements about Dropbox service issues. |
| Key | Description |
|---|---|
| error | A value that conforms to the error data type schema defined in the definition of each route. |
| error_summary | A 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_message | An 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. |