Dropbox for HTTP Developers

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:

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

API compatibility

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.

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.

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.

/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 three authorization flows:

  • The 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.
  • The 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.
  • [Legacy. We recommend the PKCE flow.] -- 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, 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.

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
Example

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

The OIDC display, preferred_locales, and acr_values are accepted for compatibility but are non-operational.
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 and PKCE 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 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]
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
Example

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>
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 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.
refresh_token_expiration_secondsInteger? Only allowed when grant_type=authorization_code. The unix timestamp, in seconds, that the returned refresh token is valid until. If this parameter is omitted, the refresh token will be valid indefinitely, until revoked.
Returns

This endpoint returns a JSON-encoded dictionary including fields below:

When input grant_type=authorization_code:

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"
}

When input grant_type=refresh_token:

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

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: 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.
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.
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.
UnauthorizedAccountIdUsageError
This datatype comes from an imported namespace originally defined in the auth namespace.
unauthorized_account_ids List of (String)The account IDs that the caller does not have permission to use.
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. 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.

account

/set_profile_photo


Description

Sets a user's profile photo.

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

URL Structure
https://api.dropboxapi.com/2/account/set_profile_photo
Authentication
User Authentication
Endpoint format
RPC
Required Scope
account_info.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/account/set_profile_photo \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"photo\":{\".tag\":\"base64_data\",\"base64_data\":\"SW1hZ2UgZGF0YSBpbiBiYXNlNjQtZW5jb2RlZCBieXRlcy4gTm90IGEgdmFsaWQgZXhhbXBsZS4=\"}}"
Parameters
{
    "photo": {
        ".tag": "base64_data",
        "base64_data": "SW1hZ2UgZGF0YSBpbiBiYXNlNjQtZW5jb2RlZCBieXRlcy4gTm90IGEgdmFsaWQgZXhhbXBsZS4="
    }
}
SetProfilePhotoArg
photoImage to set as the user's new profile photo.
Returns
{
    "profile_photo_url": "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128"
}
SetProfilePhotoResult
profile_photo_urlStringURL for the photo representing the user, if one is set.
Errors
Example: file_type_error
{
    "error": {
        ".tag": "file_type_error"
    },
    "error_summary": "file_type_error/..."
}
Example: file_size_error
{
    "error": {
        ".tag": "file_size_error"
    },
    "error_summary": "file_size_error/..."
}
Example: dimension_error
{
    "error": {
        ".tag": "dimension_error"
    },
    "error_summary": "dimension_error/..."
}
Example: thumbnail_error
{
    "error": {
        ".tag": "thumbnail_error"
    },
    "error_summary": "thumbnail_error/..."
}
Example: transient_error
{
    "error": {
        ".tag": "transient_error"
    },
    "error_summary": "transient_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SetProfilePhotoError (open union)
file_type_errorVoidFile cannot be set as profile photo.
file_size_errorVoidFile cannot exceed 10 MB.
dimension_errorVoidImage must be larger than 128 x 128.
thumbnail_errorVoidImage could not be thumbnailed.
transient_errorVoidTemporary infrastructure failure, please retry.
See also general errors.

auth

/token/revoke


Description

Disables the access token used to authenticate the call. If there is a corresponding refresh token for the access token, this disables that refresh token, as well as any other access tokens for that refresh token.

URL Structure
https://api.dropboxapi.com/2/auth/token/revoke
Authentication
User Authentication
Endpoint format
RPC
Required Scope
None
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/auth/token/revoke \
    --header "Authorization: Bearer <get access token>"
Parameters
No parameters.
Returns
No return values.
Errors
No endpoint-specific errors.
See also general errors.

check

/app


PREVIEW - may change or disappear without notice
Description

This endpoint performs App Authentication, validating the supplied app key and secret, and returns the supplied string, to allow you to test your code and connection to the Dropbox API. It has no other effect. If you receive an HTTP 200 response with the supplied query, it indicates at least part of the Dropbox API infrastructure is working and that the app key and secret valid.

URL Structure
https://api.dropboxapi.com/2/check/app
Authentication
App Authentication
Endpoint format
RPC
Required Scope
None
Example
Get app key and secret for:
curl -X POST https://api.dropboxapi.com/2/check/app \
    --header "Authorization: Basic <get app key and secret>" \
    --header "Content-Type: application/json" \
    --data "{\"query\":\"foo\"}"
Parameters
{
    "query": "foo"
}
EchoArg
Contains the arguments to be sent to the Dropbox servers.
queryString(max_length=500)The string that you'd like to be echoed back to you. The default for this field is "".
Returns
{
    "result": "foo"
}
EchoResult
EchoResult contains the result returned from the Dropbox servers.
resultStringIf everything worked correctly, this would be the same as query. The default for this field is "".
Errors
Example: user_requested
{
    "error": {
        ".tag": "user_requested"
    },
    "error_summary": "user_requested/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
EchoError (open union)
EchoError contains the error returned from the Dropbox servers.
user_requestedVoidThe request was successful.
See also general errors.

/user


PREVIEW - may change or disappear without notice
Description

This endpoint performs User Authentication, validating the supplied access token, and returns the supplied string, to allow you to test your code and connection to the Dropbox API. It has no other effect. If you receive an HTTP 200 response with the supplied query, it indicates at least part of the Dropbox API infrastructure is working and that the access token is valid.

URL Structure
https://api.dropboxapi.com/2/check/user
Authentication
User Authentication
Endpoint format
RPC
Required Scope
account_info.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/check/user \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"query\":\"foo\"}"
Parameters
{
    "query": "foo"
}
EchoArg
Contains the arguments to be sent to the Dropbox servers.
queryString(max_length=500)The string that you'd like to be echoed back to you. The default for this field is "".
Returns
{
    "result": "foo"
}
EchoResult
EchoResult contains the result returned from the Dropbox servers.
resultStringIf everything worked correctly, this would be the same as query. The default for this field is "".
Errors
Example: user_requested
{
    "error": {
        ".tag": "user_requested"
    },
    "error_summary": "user_requested/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
EchoError (open union)
EchoError contains the error returned from the Dropbox servers.
user_requestedVoidThe request was successful.
See also general errors.

contacts

/delete_manual_contacts


Description

Removes all manually added contacts. You'll still keep contacts who are on your team or who you imported. New contacts will be added when you share.

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

URL Structure
https://api.dropboxapi.com/2/contacts/delete_manual_contacts
Authentication
User Authentication
Endpoint format
RPC
Required Scope
contacts.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/contacts/delete_manual_contacts \
    --header "Authorization: Bearer <get access token>"
Parameters
No parameters.
Returns
No return values.
Errors
No endpoint-specific errors.
See also general errors.

/delete_manual_contacts_batch


Description

Removes manually added contacts from the given list.

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

URL Structure
https://api.dropboxapi.com/2/contacts/delete_manual_contacts_batch
Authentication
User Authentication
Endpoint format
RPC
Required Scope
contacts.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/contacts/delete_manual_contacts_batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"email_addresses\":[\"contactemailaddress1@domain.com\",\"contactemailaddress2@domain.com\"]}"
Parameters
{
    "email_addresses": [
        "contactemailaddress1@domain.com",
        "contactemailaddress2@domain.com"
    ]
}
DeleteManualContactsArg
email_addresses List of (String(max_length=255, pattern="^['#&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*\.[A-Za-z]{2,15}$"))List of manually added contacts to be deleted.
Returns
No return values.
Errors
DeleteManualContactsError (open union)
contacts_not_found List of (String(max_length=255, pattern="^['#&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*\.[A-Za-z]{2,15}$"))Can't delete contacts from this list. Make sure the list only has manually added contacts. The deletion was cancelled.
See also general errors.

file_properties

This namespace contains helpers for property and template metadata endpoints. These endpoints enable you to tag arbitrary key/value data to Dropbox files. The most basic unit in this namespace is the :type:`PropertyField`. These fields encapsulate the actual key/value data. Fields are added to a Dropbox file using a :type:`PropertyGroup`. Property groups contain a reference to a Dropbox file and a :type:`PropertyGroupTemplate`. Property groups are uniquely identified by the combination of their associated Dropbox file and template. The :type:`PropertyGroupTemplate` is a way of restricting the possible key names and value types of the data within a property group. The possible key names and value types are explicitly enumerated using :type:`PropertyFieldTemplate` objects. You can think of a property group template as a class definition for a particular key/value metadata object, and the property groups themselves as the instantiations of these objects. Templates are owned either by a user/app pair or team/app pair. Templates and their associated properties can't be accessed by any app other than the app that created them, and even then, only when the app is linked with the owner of the template (either a user or team). User-owned templates are accessed via the user-auth file_properties/templates/*_for_user endpoints, while team-owned templates are accessed via the team-auth file_properties/templates/*_for_team endpoints. Properties associated with either type of template can be accessed via the user-auth properties/* endpoints. Finally, properties can be accessed from a number of endpoints that return metadata, including `files/get_metadata`, and `files/list_folder`. Properties can also be added during upload, using `files/upload`.

/properties/add


Description

Add property groups to a Dropbox file. See templates/add_for_user or templates/add_for_team to create new templates.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/add
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/add \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/my_awesome/word.docx\",\"property_groups\":[{\"fields\":[{\"name\":\"Security Policy\",\"value\":\"Confidential\"}],\"template_id\":\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ]
}
AddPropertiesArg
pathString(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)")A unique identifier for the file or folder.
property_groupsList of ()The property groups which are to be added to a Dropbox file. No two groups in the input should refer to the same template.
Returns
No return values.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: unsupported_folder
{
    "error": {
        ".tag": "unsupported_folder"
    },
    "error_summary": "unsupported_folder/..."
}
Example: property_field_too_large
{
    "error": {
        ".tag": "property_field_too_large"
    },
    "error_summary": "property_field_too_large/..."
}
Example: does_not_fit_template
{
    "error": {
        ".tag": "does_not_fit_template"
    },
    "error_summary": "does_not_fit_template/..."
}
Example: duplicate_property_groups
{
    "error": {
        ".tag": "duplicate_property_groups"
    },
    "error_summary": "duplicate_property_groups/..."
}
Example: property_group_already_exists
{
    "error": {
        ".tag": "property_group_already_exists"
    },
    "error_summary": "property_group_already_exists/..."
}
AddPropertiesError (union)
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
path
unsupported_folderVoidThis folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_field_too_largeVoidOne or more of the supplied property field values is too large.
does_not_fit_templateVoidOne or more of the supplied property fields does not conform to the template specifications.
duplicate_property_groupsVoidThere are 2 or more property groups referring to the same templates in the input.
property_group_already_existsVoidA property group associated with this template and file already exists.
See also general errors.

/properties/overwrite


Description

Overwrite property groups associated with a file. This endpoint should be used instead of properties/update when property groups are being updated via a "snapshot" instead of via a "delta". In other words, this endpoint will delete all omitted fields from a property group, whereas properties/update will only delete fields that are explicitly marked for deletion.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/overwrite
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/overwrite \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/my_awesome/word.docx\",\"property_groups\":[{\"fields\":[{\"name\":\"Security Policy\",\"value\":\"Confidential\"}],\"template_id\":\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ]
}
OverwritePropertyGroupArg
pathString(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)")A unique identifier for the file or folder.
property_groupsList of (, min_items=1)The property groups "snapshot" updates to force apply. No two groups in the input should refer to the same template.
Returns
No return values.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: unsupported_folder
{
    "error": {
        ".tag": "unsupported_folder"
    },
    "error_summary": "unsupported_folder/..."
}
Example: property_field_too_large
{
    "error": {
        ".tag": "property_field_too_large"
    },
    "error_summary": "property_field_too_large/..."
}
Example: does_not_fit_template
{
    "error": {
        ".tag": "does_not_fit_template"
    },
    "error_summary": "does_not_fit_template/..."
}
Example: duplicate_property_groups
{
    "error": {
        ".tag": "duplicate_property_groups"
    },
    "error_summary": "duplicate_property_groups/..."
}
InvalidPropertyGroupError (union)
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
path
unsupported_folderVoidThis folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_field_too_largeVoidOne or more of the supplied property field values is too large.
does_not_fit_templateVoidOne or more of the supplied property fields does not conform to the template specifications.
duplicate_property_groupsVoidThere are 2 or more property groups referring to the same templates in the input.
See also general errors.

/properties/remove


Description

Permanently removes the specified property group from the file. To remove specific property field key value pairs, see properties/update. To update a template, see templates/update_for_user or templates/update_for_team. To remove a template, see templates/remove_for_user or templates/remove_for_team.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/remove
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/remove \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/my_awesome/word.docx\",\"property_template_ids\":[\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "property_template_ids": [
        "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
    ]
}
RemovePropertiesArg
pathString(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)")A unique identifier for the file or folder.
property_template_ids List of (String(min_length=1, pattern="(/|ptid:).*"))A list of identifiers for a template created by templates/add_for_user or templates/add_for_team.
Returns
No return values.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: unsupported_folder
{
    "error": {
        ".tag": "unsupported_folder"
    },
    "error_summary": "unsupported_folder/..."
}
RemovePropertiesError (union)
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
path
unsupported_folderVoidThis folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_group_lookup
See also general errors.

/properties/search


Description

Search across property templates for particular property field values.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/search
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/search \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"queries\":[{\"logical_operator\":\"or_operator\",\"mode\":{\".tag\":\"field_name\",\"field_name\":\"Security\"},\"query\":\"Confidential\"}],\"template_filter\":\"filter_none\"}"
Parameters
{
    "queries": [
        {
            "logical_operator": "or_operator",
            "mode": {
                ".tag": "field_name",
                "field_name": "Security"
            },
            "query": "Confidential"
        }
    ],
    "template_filter": "filter_none"
}
PropertiesSearchArg
queriesList of (, min_items=1)Queries to search.
template_filterFilter results to contain only properties associated with these template IDs. The default for this union is filter_none.
Returns
{
    "matches": [
        {
            "id": "id:a4ayc_80_OEAAAAAAAAAXz",
            "is_deleted": false,
            "path": "/my_awesome/word.docx",
            "property_groups": [
                {
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ],
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                }
            ]
        }
    ]
}
PropertiesSearchResult
matchesList of ()A list (possibly empty) of matches for the query.
cursor String(min_length=1)?Pass the cursor into properties/search/continue to continue to receive search results. Cursor will be null when there are no more results. This field is optional.
Errors
PropertiesSearchError (open union)
property_group_lookup
See also general errors.

/properties/search/continue


Description

Once a cursor has been retrieved from properties/search, use this to paginate through all search results.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/search/continue
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/search/continue \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
PropertiesSearchContinueArg
cursorString(min_length=1)The cursor returned by your last call to properties/search or properties/search/continue.
Returns
{
    "matches": [
        {
            "id": "id:a4ayc_80_OEAAAAAAAAAXz",
            "is_deleted": false,
            "path": "/my_awesome/word.docx",
            "property_groups": [
                {
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ],
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                }
            ]
        }
    ]
}
PropertiesSearchResult
matchesList of ()A list (possibly empty) of matches for the query.
cursor String(min_length=1)?Pass the cursor into properties/search/continue to continue to receive search results. Cursor will be null when there are no more results. This field is optional.
Errors
Example: reset
{
    "error": {
        ".tag": "reset"
    },
    "error_summary": "reset/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
PropertiesSearchContinueError (open union)
resetVoidIndicates that the cursor has been invalidated. Call properties/search to obtain a new cursor.
See also general errors.

/properties/update


Description

Add, update or remove properties associated with the supplied file and templates. This endpoint should be used instead of properties/overwrite when property groups are being updated via a "delta" instead of via a "snapshot" . In other words, this endpoint will not delete any omitted fields from a property group, whereas properties/overwrite will delete any fields that are omitted from a property group.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/update
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/update \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/my_awesome/word.docx\",\"update_property_groups\":[{\"add_or_update_fields\":[{\"name\":\"Security Policy\",\"value\":\"Confidential\"}],\"remove_fields\":[],\"template_id\":\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "update_property_groups": [
        {
            "add_or_update_fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "remove_fields": [],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ]
}
UpdatePropertiesArg
pathString(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)")A unique identifier for the file or folder.
update_property_groupsList of ()The property groups "delta" updates to apply.
Returns
No return values.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: unsupported_folder
{
    "error": {
        ".tag": "unsupported_folder"
    },
    "error_summary": "unsupported_folder/..."
}
Example: property_field_too_large
{
    "error": {
        ".tag": "property_field_too_large"
    },
    "error_summary": "property_field_too_large/..."
}
Example: does_not_fit_template
{
    "error": {
        ".tag": "does_not_fit_template"
    },
    "error_summary": "does_not_fit_template/..."
}
Example: duplicate_property_groups
{
    "error": {
        ".tag": "duplicate_property_groups"
    },
    "error_summary": "duplicate_property_groups/..."
}
UpdatePropertiesError (union)
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
path
unsupported_folderVoidThis folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_field_too_largeVoidOne or more of the supplied property field values is too large.
does_not_fit_templateVoidOne or more of the supplied property fields does not conform to the template specifications.
duplicate_property_groupsVoidThere are 2 or more property groups referring to the same templates in the input.
property_group_lookup
See also general errors.

/templates/add_for_user


Description

Add a template associated with a user. See properties/add to add properties to a file. This endpoint can't be called on a team member or admin's behalf.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/templates/add_for_user
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/templates/add_for_user \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"description\":\"These properties describe how confidential this file or folder is.\",\"fields\":[{\"description\":\"This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.\",\"name\":\"Security Policy\",\"type\":\"string\"}],\"name\":\"Security\"}"
Parameters
{
    "description": "These properties describe how confidential this file or folder is.",
    "fields": [
        {
            "description": "This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.",
            "name": "Security Policy",
            "type": "string"
        }
    ],
    "name": "Security"
}
AddTemplateArg
nameStringDisplay name for the template. Template names can be up to 256 bytes.
descriptionStringDescription for the template. Template descriptions can be up to 1024 bytes.
fieldsList of ()Definitions of the property fields associated with this template. There can be up to 32 properties in a single template.
Returns
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
AddTemplateResult
template_idString(min_length=1, pattern="(/|ptid:).*")An identifier for template added by See templates/add_for_user or templates/add_for_team.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: conflicting_property_names
{
    "error": {
        ".tag": "conflicting_property_names"
    },
    "error_summary": "conflicting_property_names/..."
}
Example: too_many_properties
{
    "error": {
        ".tag": "too_many_properties"
    },
    "error_summary": "too_many_properties/..."
}
Example: too_many_templates
{
    "error": {
        ".tag": "too_many_templates"
    },
    "error_summary": "too_many_templates/..."
}
Example: template_attribute_too_large
{
    "error": {
        ".tag": "template_attribute_too_large"
    },
    "error_summary": "template_attribute_too_large/..."
}
ModifyTemplateError (union)
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
conflicting_property_namesVoidA property field key with that name already exists in the template.
too_many_propertiesVoidThere are too many properties in the changed template. The maximum number of properties per template is 32.
too_many_templatesVoidThere are too many templates for the team.
template_attribute_too_largeVoidThe template name, description or one or more of the property field keys is too large.
See also general errors.

/templates/get_for_user


Description

Get the schema for a specified template. This endpoint can't be called on a team member or admin's behalf.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/templates/get_for_user
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/templates/get_for_user \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"template_id\":\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}"
Parameters
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
GetTemplateArg
template_idString(min_length=1, pattern="(/|ptid:).*")An identifier for template added by route See templates/add_for_user or templates/add_for_team.
Returns
{
    "description": "These properties describe how confidential this file or folder is.",
    "fields": [
        {
            "description": "This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.",
            "name": "Security Policy",
            "type": {
                ".tag": "string"
            }
        }
    ],
    "name": "Security"
}
GetTemplateResult
nameStringDisplay name for the template. Template names can be up to 256 bytes.
descriptionStringDescription for the template. Template descriptions can be up to 1024 bytes.
fieldsList of ()Definitions of the property fields associated with this template. There can be up to 32 properties in a single template.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
TemplateError (open union)
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
See also general errors.

/templates/list_for_user


Description

Get the template identifiers for a team. To get the schema of each template use templates/get_for_user. This endpoint can't be called on a team member or admin's behalf.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/templates/list_for_user
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/templates/list_for_user \
    --header "Authorization: Bearer <get access token>"
Parameters
No parameters.
Returns
{
    "template_ids": [
        "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
    ]
}
ListTemplateResult
template_ids List of (String(min_length=1, pattern="(/|ptid:).*"))List of identifiers for templates added by See templates/add_for_user or templates/add_for_team.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
TemplateError (open union)
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
See also general errors.

/templates/remove_for_user


Description

Permanently removes the specified template created from templates/add_for_user. All properties associated with the template will also be removed. This action cannot be undone.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/templates/remove_for_user
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/templates/remove_for_user \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"template_id\":\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}"
Parameters
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
RemoveTemplateArg
template_idString(min_length=1, pattern="(/|ptid:).*")An identifier for a template created by templates/add_for_user or templates/add_for_team.
Returns
No return values.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
TemplateError (open union)
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
See also general errors.

/templates/update_for_user


Description

Update a template associated with a user. This route can update the template name, the template description and add optional properties to templates. This endpoint can't be called on a team member or admin's behalf.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/templates/update_for_user
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/templates/update_for_user \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"add_fields\":[{\"description\":\"This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.\",\"name\":\"Security Policy\",\"type\":\"string\"}],\"description\":\"These properties will describe how confidential this file or folder is.\",\"name\":\"New Security Template Name\",\"template_id\":\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}"
Parameters
{
    "add_fields": [
        {
            "description": "This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.",
            "name": "Security Policy",
            "type": "string"
        }
    ],
    "description": "These properties will describe how confidential this file or folder is.",
    "name": "New Security Template Name",
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
UpdateTemplateArg
template_idString(min_length=1, pattern="(/|ptid:).*")An identifier for template added by See templates/add_for_user or templates/add_for_team.
name String?A display name for the template. template names can be up to 256 bytes. This field is optional.
description String?Description for the new template. Template descriptions can be up to 1024 bytes. This field is optional.
add_fieldsList of ()?Property field templates to be added to the group template. There can be up to 32 properties in a single template. This field is optional.
Returns
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
UpdateTemplateResult
template_idString(min_length=1, pattern="(/|ptid:).*")An identifier for template added by route See templates/add_for_user or templates/add_for_team.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: conflicting_property_names
{
    "error": {
        ".tag": "conflicting_property_names"
    },
    "error_summary": "conflicting_property_names/..."
}
Example: too_many_properties
{
    "error": {
        ".tag": "too_many_properties"
    },
    "error_summary": "too_many_properties/..."
}
Example: too_many_templates
{
    "error": {
        ".tag": "too_many_templates"
    },
    "error_summary": "too_many_templates/..."
}
Example: template_attribute_too_large
{
    "error": {
        ".tag": "template_attribute_too_large"
    },
    "error_summary": "template_attribute_too_large/..."
}
ModifyTemplateError (union)
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
conflicting_property_namesVoidA property field key with that name already exists in the template.
too_many_propertiesVoidThere are too many properties in the changed template. The maximum number of properties per template is 32.
too_many_templatesVoidThere are too many templates for the team.
template_attribute_too_largeVoidThe template name, description or one or more of the property field keys is too large.
See also general errors.

file_requests

This namespace contains endpoints and data types for file request operations.

/count


Description

Returns the total number of file requests owned by this user. Includes both open and closed file requests.

URL Structure
https://api.dropboxapi.com/2/file_requests/count
Authentication
User Authentication
Endpoint format
RPC
Required Scope
file_requests.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/count \
    --header "Authorization: Bearer <get access token>"
Parameters
No parameters.
Returns
{
    "file_request_count": 15
}
CountFileRequestsResult
Result for count.
file_request_countUInt64The number file requests owner by this user.
Errors
Example: disabled_for_team
{
    "error": {
        ".tag": "disabled_for_team"
    },
    "error_summary": "disabled_for_team/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
CountFileRequestsError (union)
There was an error counting the file requests.
disabled_for_teamVoidThis user's Dropbox Business team doesn't allow file requests.
See also general errors.

/create


Description

Creates a file request for this user.

URL Structure
https://api.dropboxapi.com/2/file_requests/create
Authentication
User Authentication
Endpoint format
RPC
Required Scope
file_requests.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/create \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"deadline\":{\"allow_late_uploads\":\"seven_days\",\"deadline\":\"2020-10-12T17:00:00Z\"},\"destination\":\"/File Requests/Homework\",\"open\":true,\"title\":\"Homework submission\"}"
Parameters
{
    "deadline": {
        "allow_late_uploads": "seven_days",
        "deadline": "2020-10-12T17:00:00Z"
    },
    "destination": "/File Requests/Homework",
    "open": true,
    "title": "Homework submission"
}
CreateFileRequestArgs
Arguments for create.
titleString(min_length=1)The title of the file request. Must not be empty.
destinationString(pattern="/(.|[\r\n])*")The path of the folder in the Dropbox where uploaded files will be sent. For apps with the app folder permission, this will be relative to the app folder.
deadline?The deadline for the file request. Deadlines can only be set by Professional and Business accounts. This field is optional.
openBooleanWhether or not the file request should be open. If the file request is closed, it will not accept any file submissions, but it can be opened later. The default for this field is True.
description String?A description of the file request. This field is optional.
video_project_id String?If this request was created from video project, its id. This field is optional.
Returns
{
    "created": "2015-10-05T17:00:00Z",
    "deadline": {
        "allow_late_uploads": {
            ".tag": "seven_days"
        },
        "deadline": "2020-10-12T17:00:00Z"
    },
    "description": "Please submit your homework here.",
    "destination": "/File Requests/Homework",
    "file_count": 3,
    "id": "oaCAVmEyrqYnkZX9955Y",
    "is_open": true,
    "title": "Homework submission",
    "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y"
}
Example: with_deadline
{
    "created": "2015-11-02T04:00:00Z",
    "deadline": {
        "deadline": "2020-10-12T17:00:00Z"
    },
    "destination": "/Photo contest entries",
    "file_count": 105,
    "id": "BAJ7IrRGicQKGToykQdB",
    "is_open": true,
    "title": "Photo contest submission",
    "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB"
}
Example: with_no_deadline
{
    "created": "2015-12-15T13:02:00Z",
    "destination": "/Wedding photos",
    "file_count": 37,
    "id": "rxwMPvK3ATTa0VxOJu5T",
    "is_open": true,
    "title": "Wedding photo submission",
    "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T"
}
FileRequest
A file request for receiving files into the user's Dropbox account.
idString(min_length=1, pattern="[-_0-9a-zA-Z]+")The ID of the file request.
urlString(min_length=1)The URL of the file request.
titleString(min_length=1)The title of the file request.
createdTimestamp(format="%Y-%m-%dT%H:%M:%SZ")When this file request was created.
is_openBooleanWhether or not the file request is open. If the file request is closed, it will not accept any more file submissions.
file_countInt64The number of files this file request has received.
destination String(pattern="/(.|[\r\n])*")?The path of the folder in the Dropbox where uploaded files will be sent. This can be None if the destination was removed. For apps with the app folder permission, this will be relative to the app folder. This field is optional.
deadline?The deadline for this file request. Only set if the request has a deadline. This field is optional.
description String?A description of the file request. This field is optional.
video_project_id String?If this request was created from video project, its id. This field is optional.
Errors
Example: disabled_for_team
{
    "error": {
        ".tag": "disabled_for_team"
    },
    "error_summary": "disabled_for_team/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: not_found
{
    "error": {
        ".tag": "not_found"
    },
    "error_summary": "not_found/..."
}
Example: not_a_folder
{
    "error": {
        ".tag": "not_a_folder"
    },
    "error_summary": "not_a_folder/..."
}
Example: app_lacks_access
{
    "error": {
        ".tag": "app_lacks_access"
    },
    "error_summary": "app_lacks_access/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: validation_error
{
    "error": {
        ".tag": "validation_error"
    },
    "error_summary": "validation_error/..."
}
Example: invalid_location
{
    "error": {
        ".tag": "invalid_location"
    },
    "error_summary": "invalid_location/..."
}
Example: rate_limit
{
    "error": {
        ".tag": "rate_limit"
    },
    "error_summary": "rate_limit/..."
}
CreateFileRequestError (union)
There was an error creating the file request.
disabled_for_teamVoidThis user's Dropbox Business team doesn't allow file requests.
not_foundVoidThis file request ID was not found.
not_a_folderVoidThe specified path is not a folder.
app_lacks_accessVoidThis file request is not accessible to this app. Apps with the app folder permission can only access file requests in their app folder.
no_permissionVoidThis user doesn't have permission to access or modify this file request.
email_unverifiedVoidThis user's email address is not verified. File requests are only available on accounts with a verified email address. Users can verify their email address here.
validation_errorVoidThere was an error validating the request. For example, the title was invalid, or there were disallowed characters in the destination path.
invalid_locationVoidFile requests are not available on the specified folder.
rate_limitVoidThe user has reached the rate limit for creating file requests. The limit is currently 4000 file requests total.
See also general errors.

/delete


Description

Delete a batch of closed file requests.

URL Structure
https://api.dropboxapi.com/2/file_requests/delete
Authentication
User Authentication
Endpoint format
RPC
Required Scope
file_requests.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/delete \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"ids\":[\"oaCAVmEyrqYnkZX9955Y\",\"BaZmehYoXMPtaRmfTbSG\"]}"
Parameters
{
    "ids": [
        "oaCAVmEyrqYnkZX9955Y",
        "BaZmehYoXMPtaRmfTbSG"
    ]
}
DeleteFileRequestArgs
Arguments for delete.
ids List of (String(min_length=1, pattern="[-_0-9a-zA-Z]+"))List IDs of the file requests to delete.
Returns
{
    "file_requests": [
        {
            "created": "2015-10-05T17:00:00Z",
            "deadline": {
                "allow_late_uploads": {
                    ".tag": "seven_days"
                },
                "deadline": "2020-10-12T17:00:00Z"
            },
            "description": "Please submit your homework here.",
            "destination": "/File Requests/Homework",
            "file_count": 3,
            "id": "oaCAVmEyrqYnkZX9955Y",
            "is_open": true,
            "title": "Homework submission",
            "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y"
        },
        {
            "created": "2015-11-02T04:00:00Z",
            "deadline": {
                "deadline": "2020-10-12T17:00:00Z"
            },
            "destination": "/Photo contest entries",
            "file_count": 105,
            "id": "BAJ7IrRGicQKGToykQdB",
            "is_open": true,
            "title": "Photo contest submission",
            "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB"
        },
        {
            "created": "2015-12-15T13:02:00Z",
            "destination": "/Wedding photos",
            "file_count": 37,
            "id": "rxwMPvK3ATTa0VxOJu5T",
            "is_open": true,
            "title": "Wedding photo submission",
            "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T"
        }
    ]
}
DeleteFileRequestsResult
Result for delete.
file_requestsList of ()The file requests deleted by the request.
Errors
Example: disabled_for_team
{
    "error": {
        ".tag": "disabled_for_team"
    },
    "error_summary": "disabled_for_team/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: not_found
{
    "error": {
        ".tag": "not_found"
    },
    "error_summary": "not_found/..."
}
Example: not_a_folder
{
    "error": {
        ".tag": "not_a_folder"
    },
    "error_summary": "not_a_folder/..."
}
Example: app_lacks_access
{
    "error": {
        ".tag": "app_lacks_access"
    },
    "error_summary": "app_lacks_access/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: validation_error
{
    "error": {
        ".tag": "validation_error"
    },
    "error_summary": "validation_error/..."
}
Example: file_request_open
{
    "error": {
        ".tag": "file_request_open"
    },
    "error_summary": "file_request_open/..."
}
DeleteFileRequestError (union)
There was an error deleting these file requests.
disabled_for_teamVoidThis user's Dropbox Business team doesn't allow file requests.
not_foundVoidThis file request ID was not found.
not_a_folderVoidThe specified path is not a folder.
app_lacks_accessVoidThis file request is not accessible to this app. Apps with the app folder permission can only access file requests in their app folder.
no_permissionVoidThis user doesn't have permission to access or modify this file request.
email_unverifiedVoidThis user's email address is not verified. File requests are only available on accounts with a verified email address. Users can verify their email address here.
validation_errorVoidThere was an error validating the request. For example, the title was invalid, or there were disallowed characters in the destination path.
file_request_openVoidOne or more file requests currently open.
See also general errors.

/delete_all_closed


Description

Delete all closed file requests owned by this user.

URL Structure
https://api.dropboxapi.com/2/file_requests/delete_all_closed
Authentication
User Authentication
Endpoint format
RPC
Required Scope
file_requests.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/delete_all_closed \
    --header "Authorization: Bearer <get access token>"
Parameters
No parameters.
Returns
{
    "file_requests": [
        {
            "created": "2015-10-05T17:00:00Z",
            "deadline": {
                "allow_late_uploads": {
                    ".tag": "seven_days"
                },
                "deadline": "2020-10-12T17:00:00Z"
            },
            "description": "Please submit your homework here.",
            "destination": "/File Requests/Homework",
            "file_count": 3,
            "id": "oaCAVmEyrqYnkZX9955Y",
            "is_open": true,
            "title": "Homework submission",
            "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y"
        },
        {
            "created": "2015-11-02T04:00:00Z",
            "deadline": {
                "deadline": "2020-10-12T17:00:00Z"
            },
            "destination": "/Photo contest entries",
            "file_count": 105,
            "id": "BAJ7IrRGicQKGToykQdB",
            "is_open": true,
            "title": "Photo contest submission",
            "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB"
        },
        {
            "created": "2015-12-15T13:02:00Z",
            "destination": "/Wedding photos",
            "file_count": 37,
            "id": "rxwMPvK3ATTa0VxOJu5T",
            "is_open": true,
            "title": "Wedding photo submission",
            "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T"
        }
    ]
}
DeleteAllClosedFileRequestsResult
Result for delete_all_closed.
file_requestsList of ()The file requests deleted for this user.
Errors
Example: disabled_for_team
{
    "error": {
        ".tag": "disabled_for_team"
    },
    "error_summary": "disabled_for_team/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: not_found
{
    "error": {
        ".tag": "not_found"
    },
    "error_summary": "not_found/..."
}
Example: not_a_folder
{
    "error": {
        ".tag": "not_a_folder"
    },
    "error_summary": "not_a_folder/..."
}
Example: app_lacks_access
{
    "error": {
        ".tag": "app_lacks_access"
    },
    "error_summary": "app_lacks_access/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: validation_error
{
    "error": {
        ".tag": "validation_error"
    },
    "error_summary": "validation_error/..."
}
DeleteAllClosedFileRequestsError (union)
There was an error deleting all closed file requests.
disabled_for_teamVoidThis user's Dropbox Business team doesn't allow file requests.
not_foundVoidThis file request ID was not found.
not_a_folderVoidThe specified path is not a folder.
app_lacks_accessVoidThis file request is not accessible to this app. Apps with the app folder permission can only access file requests in their app folder.
no_permissionVoidThis user doesn't have permission to access or modify this file request.
email_unverifiedVoidThis user's email address is not verified. File requests are only available on accounts with a verified email address. Users can verify their email address here.
validation_errorVoidThere was an error validating the request. For example, the title was invalid, or there were disallowed characters in the destination path.
See also general errors.

/get


Description

Returns the specified file request.

URL Structure
https://api.dropboxapi.com/2/file_requests/get
Authentication
User Authentication
Endpoint format
RPC
Required Scope
file_requests.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/get \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"id\":\"oaCAVmEyrqYnkZX9955Y\"}"
Parameters
{
    "id": "oaCAVmEyrqYnkZX9955Y"
}
GetFileRequestArgs
Arguments for get.
idString(min_length=1, pattern="[-_0-9a-zA-Z]+")The ID of the file request to retrieve.
Returns
{
    "created": "2015-10-05T17:00:00Z",
    "deadline": {
        "allow_late_uploads": {
            ".tag": "seven_days"
        },
        "deadline": "2020-10-12T17:00:00Z"
    },
    "description": "Please submit your homework here.",
    "destination": "/File Requests/Homework",
    "file_count": 3,
    "id": "oaCAVmEyrqYnkZX9955Y",
    "is_open": true,
    "title": "Homework submission",
    "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y"
}
Example: with_deadline
{
    "created": "2015-11-02T04:00:00Z",
    "deadline": {
        "deadline": "2020-10-12T17:00:00Z"
    },
    "destination": "/Photo contest entries",
    "file_count": 105,
    "id": "BAJ7IrRGicQKGToykQdB",
    "is_open": true,
    "title": "Photo contest submission",
    "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB"
}
Example: with_no_deadline
{
    "created": "2015-12-15T13:02:00Z",
    "destination": "/Wedding photos",
    "file_count": 37,
    "id": "rxwMPvK3ATTa0VxOJu5T",
    "is_open": true,
    "title": "Wedding photo submission",
    "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T"
}
FileRequest
A file request for receiving files into the user's Dropbox account.
idString(min_length=1, pattern="[-_0-9a-zA-Z]+")The ID of the file request.
urlString(min_length=1)The URL of the file request.
titleString(min_length=1)The title of the file request.
createdTimestamp(format="%Y-%m-%dT%H:%M:%SZ")When this file request was created.
is_openBooleanWhether or not the file request is open. If the file request is closed, it will not accept any more file submissions.
file_countInt64The number of files this file request has received.
destination String(pattern="/(.|[\r\n])*")?The path of the folder in the Dropbox where uploaded files will be sent. This can be None if the destination was removed. For apps with the app folder permission, this will be relative to the app folder. This field is optional.
deadline?The deadline for this file request. Only set if the request has a deadline. This field is optional.
description String?A description of the file request. This field is optional.
video_project_id String?If this request was created from video project, its id. This field is optional.
Errors
Example: disabled_for_team
{
    "error": {
        ".tag": "disabled_for_team"
    },
    "error_summary": "disabled_for_team/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: not_found
{
    "error": {
        ".tag": "not_found"
    },
    "error_summary": "not_found/..."
}
Example: not_a_folder
{
    "error": {
        ".tag": "not_a_folder"
    },
    "error_summary": "not_a_folder/..."
}
Example: app_lacks_access
{
    "error": {
        ".tag": "app_lacks_access"
    },
    "error_summary": "app_lacks_access/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: validation_error
{
    "error": {
        ".tag": "validation_error"
    },
    "error_summary": "validation_error/..."
}
GetFileRequestError (union)
There was an error retrieving the specified file request.
disabled_for_teamVoidThis user's Dropbox Business team doesn't allow file requests.
not_foundVoidThis file request ID was not found.
not_a_folderVoidThe specified path is not a folder.
app_lacks_accessVoidThis file request is not accessible to this app. Apps with the app folder permission can only access file requests in their app folder.
no_permissionVoidThis user doesn't have permission to access or modify this file request.
email_unverifiedVoidThis user's email address is not verified. File requests are only available on accounts with a verified email address. Users can verify their email address here.
validation_errorVoidThere was an error validating the request. For example, the title was invalid, or there were disallowed characters in the destination path.
See also general errors.

/list


Description

Returns a list of file requests owned by this user. For apps with the app folder permission, this will only return file requests with destinations in the app folder.

URL Structure
https://api.dropboxapi.com/2/file_requests/list_v2
Authentication
User Authentication
Endpoint format
RPC
Required Scope
file_requests.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/list_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"limit\":1000}"
Parameters
{
    "limit": 1000
}
ListFileRequestsArg
Arguments for list:2.
limitUInt64The maximum number of file requests that should be returned per request. The default for this field is 1000.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "file_requests": [
        {
            "created": "2015-10-05T17:00:00Z",
            "deadline": {
                "allow_late_uploads": {
                    ".tag": "seven_days"
                },
                "deadline": "2020-10-12T17:00:00Z"
            },
            "description": "Please submit your homework here.",
            "destination": "/File Requests/Homework",
            "file_count": 3,
            "id": "oaCAVmEyrqYnkZX9955Y",
            "is_open": true,
            "title": "Homework submission",
            "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y"
        },
        {
            "created": "2015-11-02T04:00:00Z",
            "deadline": {
                "deadline": "2020-10-12T17:00:00Z"
            },
            "destination": "/Photo contest entries",
            "file_count": 105,
            "id": "BAJ7IrRGicQKGToykQdB",
            "is_open": true,
            "title": "Photo contest submission",
            "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB"
        },
        {
            "created": "2015-12-15T13:02:00Z",
            "destination": "/Wedding photos",
            "file_count": 37,
            "id": "rxwMPvK3ATTa0VxOJu5T",
            "is_open": true,
            "title": "Wedding photo submission",
            "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T"
        }
    ],
    "has_more": true
}
ListFileRequestsV2Result
Result for list:2 and list/continue.
file_requestsList of ()The file requests owned by this user. Apps with the app folder permission will only see file requests in their app folder.
cursorStringPass the cursor into list/continue to obtain additional file requests.
has_moreBooleanIs true if there are additional file requests that have not been returned yet. An additional call to :route:list/continue` can retrieve them.
Errors
Example: disabled_for_team
{
    "error": {
        ".tag": "disabled_for_team"
    },
    "error_summary": "disabled_for_team/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ListFileRequestsError (union)
There was an error retrieving the file requests.
disabled_for_teamVoidThis user's Dropbox Business team doesn't allow file requests.
See also general errors.

/list/continue


Description

Once a cursor has been retrieved from list:2, use this to paginate through all file requests. The cursor must come from a previous call to list:2 or list/continue.

URL Structure
https://api.dropboxapi.com/2/file_requests/list/continue
Authentication
User Authentication
Endpoint format
RPC
Required Scope
file_requests.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/list/continue \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
ListFileRequestsContinueArg
cursorStringThe cursor returned by the previous API call specified in the endpoint description.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "file_requests": [
        {
            "created": "2015-10-05T17:00:00Z",
            "deadline": {
                "allow_late_uploads": {
                    ".tag": "seven_days"
                },
                "deadline": "2020-10-12T17:00:00Z"
            },
            "description": "Please submit your homework here.",
            "destination": "/File Requests/Homework",
            "file_count": 3,
            "id": "oaCAVmEyrqYnkZX9955Y",
            "is_open": true,
            "title": "Homework submission",
            "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y"
        },
        {
            "created": "2015-11-02T04:00:00Z",
            "deadline": {
                "deadline": "2020-10-12T17:00:00Z"
            },
            "destination": "/Photo contest entries",
            "file_count": 105,
            "id": "BAJ7IrRGicQKGToykQdB",
            "is_open": true,
            "title": "Photo contest submission",
            "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB"
        },
        {
            "created": "2015-12-15T13:02:00Z",
            "destination": "/Wedding photos",
            "file_count": 37,
            "id": "rxwMPvK3ATTa0VxOJu5T",
            "is_open": true,
            "title": "Wedding photo submission",
            "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T"
        }
    ],
    "has_more": true
}
ListFileRequestsV2Result
Result for list:2 and list/continue.
file_requestsList of ()The file requests owned by this user. Apps with the app folder permission will only see file requests in their app folder.
cursorStringPass the cursor into list/continue to obtain additional file requests.
has_moreBooleanIs true if there are additional file requests that have not been returned yet. An additional call to :route:list/continue` can retrieve them.
Errors
Example: disabled_for_team
{
    "error": {
        ".tag": "disabled_for_team"
    },
    "error_summary": "disabled_for_team/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: invalid_cursor
{
    "error": {
        ".tag": "invalid_cursor"
    },
    "error_summary": "invalid_cursor/..."
}
ListFileRequestsContinueError (union)
There was an error retrieving the file requests.
disabled_for_teamVoidThis user's Dropbox Business team doesn't allow file requests.
invalid_cursorVoidThe cursor is invalid.
See also general errors.

/update


Description

Update a file request.

URL Structure
https://api.dropboxapi.com/2/file_requests/update
Authentication
User Authentication
Endpoint format
RPC
Required Scope
file_requests.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/update \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"deadline\":{\".tag\":\"update\",\"allow_late_uploads\":\"seven_days\",\"deadline\":\"2020-10-12T17:00:00Z\"},\"destination\":\"/File Requests/Homework\",\"id\":\"oaCAVmEyrqYnkZX9955Y\",\"open\":true,\"title\":\"Homework submission\"}"
Parameters
{
    "deadline": {
        ".tag": "update",
        "allow_late_uploads": "seven_days",
        "deadline": "2020-10-12T17:00:00Z"
    },
    "destination": "/File Requests/Homework",
    "id": "oaCAVmEyrqYnkZX9955Y",
    "open": true,
    "title": "Homework submission"
}
UpdateFileRequestArgs
Arguments for update.
idString(min_length=1, pattern="[-_0-9a-zA-Z]+")The ID of the file request to update.
title String(min_length=1)?The new title of the file request. Must not be empty. This field is optional.
destination String(pattern="/(.|[\r\n])*")?The new path of the folder in the Dropbox where uploaded files will be sent. For apps with the app folder permission, this will be relative to the app folder. This field is optional.
deadlineThe new deadline for the file request. Deadlines can only be set by Professional and Business accounts. The default for this union is no_update.
open Boolean?Whether to set this file request as open or closed. This field is optional.
description String?The description of the file request. This field is optional.
Returns
{
    "created": "2015-10-05T17:00:00Z",
    "deadline": {
        "allow_late_uploads": {
            ".tag": "seven_days"
        },
        "deadline": "2020-10-12T17:00:00Z"
    },
    "description": "Please submit your homework here.",
    "destination": "/File Requests/Homework",
    "file_count": 3,
    "id": "oaCAVmEyrqYnkZX9955Y",
    "is_open": true,
    "title": "Homework submission",
    "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y"
}
Example: with_deadline
{
    "created": "2015-11-02T04:00:00Z",
    "deadline": {
        "deadline": "2020-10-12T17:00:00Z"
    },
    "destination": "/Photo contest entries",
    "file_count": 105,
    "id": "BAJ7IrRGicQKGToykQdB",
    "is_open": true,
    "title": "Photo contest submission",
    "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB"
}
Example: with_no_deadline
{
    "created": "2015-12-15T13:02:00Z",
    "destination": "/Wedding photos",
    "file_count": 37,
    "id": "rxwMPvK3ATTa0VxOJu5T",
    "is_open": true,
    "title": "Wedding photo submission",
    "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T"
}
FileRequest
A file request for receiving files into the user's Dropbox account.
idString(min_length=1, pattern="[-_0-9a-zA-Z]+")The ID of the file request.
urlString(min_length=1)The URL of the file request.
titleString(min_length=1)The title of the file request.
createdTimestamp(format="%Y-%m-%dT%H:%M:%SZ")When this file request was created.
is_openBooleanWhether or not the file request is open. If the file request is closed, it will not accept any more file submissions.
file_countInt64The number of files this file request has received.
destination String(pattern="/(.|[\r\n])*")?The path of the folder in the Dropbox where uploaded files will be sent. This can be None if the destination was removed. For apps with the app folder permission, this will be relative to the app folder. This field is optional.
deadline?The deadline for this file request. Only set if the request has a deadline. This field is optional.
description String?A description of the file request. This field is optional.
video_project_id String?If this request was created from video project, its id. This field is optional.
Errors
Example: disabled_for_team
{
    "error": {
        ".tag": "disabled_for_team"
    },
    "error_summary": "disabled_for_team/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: not_found
{
    "error": {
        ".tag": "not_found"
    },
    "error_summary": "not_found/..."
}
Example: not_a_folder
{
    "error": {
        ".tag": "not_a_folder"
    },
    "error_summary": "not_a_folder/..."
}
Example: app_lacks_access
{
    "error": {
        ".tag": "app_lacks_access"
    },
    "error_summary": "app_lacks_access/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: validation_error
{
    "error": {
        ".tag": "validation_error"
    },
    "error_summary": "validation_error/..."
}
UpdateFileRequestError (union)
There is an error updating the file request.
disabled_for_teamVoidThis user's Dropbox Business team doesn't allow file requests.
not_foundVoidThis file request ID was not found.
not_a_folderVoidThe specified path is not a folder.
app_lacks_accessVoidThis file request is not accessible to this app. Apps with the app folder permission can only access file requests in their app folder.
no_permissionVoidThis user doesn't have permission to access or modify this file request.
email_unverifiedVoidThis user's email address is not verified. File requests are only available on accounts with a verified email address. Users can verify their email address here.
validation_errorVoidThere was an error validating the request. For example, the title was invalid, or there were disallowed characters in the destination path.
See also general errors.

files

This namespace contains endpoints and data types for basic file operations.

/copy


Description

Copy a file or folder to a different location in the user's Dropbox. If the source path is a folder all its contents will be copied.

URL Structure
https://api.dropboxapi.com/2/files/copy_v2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"allow_ownership_transfer\":false,\"allow_shared_folder\":false,\"autorename\":false,\"from_path\":\"/Homework/math\",\"to_path\":\"/Homework/algebra\"}"
Parameters
{
    "allow_ownership_transfer": false,
    "allow_shared_folder": false,
    "autorename": false,
    "from_path": "/Homework/math",
    "to_path": "/Homework/algebra"
}
RelocationArg
from_pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)")Path in the user's Dropbox to be copied or moved.
to_pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)")Path in the user's Dropbox that is the destination.
allow_shared_folderdeprecatedBooleanField is deprecated. This flag has no effect. The default for this field is False.
autorenameBooleanIf there's a conflict, have the Dropbox server try to autorename the file to avoid the conflict. The default for this field is False.
allow_ownership_transferBooleanAllow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies. The default for this field is False.
Returns
{
    "metadata": {
        ".tag": "file",
        "client_modified": "2015-05-12T15:50:38Z",
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "file_lock_info": {
            "created": "2015-05-12T15:50:38Z",
            "is_lockholder": true,
            "lockholder_name": "Imaginary User"
        },
        "has_explicit_shared_members": false,
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "is_downloadable": true,
        "name": "Prime_Numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "path_lower": "/homework/math/prime_numbers.txt",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "rev": "a1c10ce0dd78",
        "server_modified": "2015-05-12T15:50:38Z",
        "sharing_info": {
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "parent_shared_folder_id": "84528192421",
            "read_only": true
        },
        "size": 7212
    }
}
RelocationResult
metadataMetadata of the relocated object.
Errors
Example: cant_copy_shared_folder
{
    "error": {
        ".tag": "cant_copy_shared_folder"
    },
    "error_summary": "cant_copy_shared_folder/..."
}
Example: cant_nest_shared_folder
{
    "error": {
        ".tag": "cant_nest_shared_folder"
    },
    "error_summary": "cant_nest_shared_folder/..."
}
Example: cant_move_folder_into_itself
{
    "error": {
        ".tag": "cant_move_folder_into_itself"
    },
    "error_summary": "cant_move_folder_into_itself/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: duplicated_or_nested_paths
{
    "error": {
        ".tag": "duplicated_or_nested_paths"
    },
    "error_summary": "duplicated_or_nested_paths/..."
}
Example: cant_transfer_ownership
{
    "error": {
        ".tag": "cant_transfer_ownership"
    },
    "error_summary": "cant_transfer_ownership/..."
}
Example: insufficient_quota
{
    "error": {
        ".tag": "insufficient_quota"
    },
    "error_summary": "insufficient_quota/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: cant_move_shared_folder
{
    "error": {
        ".tag": "cant_move_shared_folder"
    },
    "error_summary": "cant_move_shared_folder/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
RelocationError (open union)
from_lookup
from_write
to
cant_copy_shared_folderVoidShared folders can't be copied.
cant_nest_shared_folderVoidYour move operation would result in nested shared folders. This is not allowed.
cant_move_folder_into_itselfVoidYou cannot move a folder into itself.
too_many_filesVoidThe operation would involve more than 10,000 files and folders.
duplicated_or_nested_pathsVoidThere are duplicated/nested paths among RelocationArg.from_path and RelocationArg.to_path.
cant_transfer_ownershipVoidYour move operation would result in an ownership transfer. You may reissue the request with the field RelocationArg.allow_ownership_transfer to true.
insufficient_quotaVoidThe current user does not have enough space to move or copy the files.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
cant_move_shared_folderVoidCan't move the shared folder to the given destination.
cant_move_into_vaultSome content cannot be moved into Vault under certain circumstances, see detailed error.
cant_move_into_familySome content cannot be moved into the Family Room folder under certain circumstances, see detailed error.
See also general errors.

/copy_batch


Description

Copy multiple files or folders to different locations at once in the user's Dropbox. This route will replace copy_batch:1. The main difference is this route will return status for each entry, while copy_batch:1 raises failure if any entry fails. This route will either finish synchronously, or return a job ID and do the async copy job in background. Please use copy_batch/check:2 to check the job status.

URL Structure
https://api.dropboxapi.com/2/files/copy_batch_v2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy_batch_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"autorename\":false,\"entries\":[{\"from_path\":\"/Homework/math\",\"to_path\":\"/Homework/algebra\"}]}"
Parameters
{
    "autorename": false,
    "entries": [
        {
            "from_path": "/Homework/math",
            "to_path": "/Homework/algebra"
        }
    ]
}
RelocationBatchArgBase
entriesList of (, min_items=1, max_items=1000)List of entries to be moved or copied. Each entry is RelocationPath.
autorenameBooleanIf there's a conflict with any file, have the Dropbox server try to autorename that file to avoid the conflict. The default for this field is False.
Returns
Example: complete
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "success": {
                ".tag": "file",
                "client_modified": "2015-05-12T15:50:38Z",
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "file_lock_info": {
                    "created": "2015-05-12T15:50:38Z",
                    "is_lockholder": true,
                    "lockholder_name": "Imaginary User"
                },
                "has_explicit_shared_members": false,
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "is_downloadable": true,
                "name": "Prime_Numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "path_lower": "/homework/math/prime_numbers.txt",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "rev": "a1c10ce0dd78",
                "server_modified": "2015-05-12T15:50:38Z",
                "sharing_info": {
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "parent_shared_folder_id": "84528192421",
                    "read_only": true
                },
                "size": 7212
            }
        }
    ]
}
Example: async_job_id
{
    ".tag": "async_job_id",
    "async_job_id": "34g93hh34h04y384084"
}
RelocationBatchV2Launch (union)
Result returned by copy_batch:2 or move_batch:2 that may either launch an asynchronous job or complete synchronously.
async_job_idString(min_length=1)This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
complete
Errors
No endpoint-specific errors.
See also general errors.

/copy_batch/check


Description

Returns the status of an asynchronous job for copy_batch:2. It returns list of results for each entry.

URL Structure
https://api.dropboxapi.com/2/files/copy_batch/check_v2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy_batch/check_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"async_job_id\":\"34g93hh34h04y384084\"}"
Parameters
{
    "async_job_id": "34g93hh34h04y384084"
}
PollArg
Arguments for methods that poll the status of an asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Returns
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "success": {
                ".tag": "file",
                "client_modified": "2015-05-12T15:50:38Z",
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "file_lock_info": {
                    "created": "2015-05-12T15:50:38Z",
                    "is_lockholder": true,
                    "lockholder_name": "Imaginary User"
                },
                "has_explicit_shared_members": false,
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "is_downloadable": true,
                "name": "Prime_Numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "path_lower": "/homework/math/prime_numbers.txt",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "rev": "a1c10ce0dd78",
                "server_modified": "2015-05-12T15:50:38Z",
                "sharing_info": {
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "parent_shared_folder_id": "84528192421",
                    "read_only": true
                },
                "size": 7212
            }
        }
    ]
}
Example: in_progress
{
    ".tag": "in_progress"
}
RelocationBatchV2JobStatus (union)
Result returned by copy_batch/check:2 or move_batch/check:2 that may either be in progress or completed with result for each entry.
in_progressVoidThe asynchronous job is still in progress.
completeThe copy or move batch job has finished.
Errors
Example: invalid_async_job_id
{
    "error": {
        ".tag": "invalid_async_job_id"
    },
    "error_summary": "invalid_async_job_id/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
PollError (open union)
Error returned by methods for polling the status of asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
invalid_async_job_idVoidThe job ID is invalid.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/copy_reference/get


Description

Get a copy reference to a file or folder. This reference string can be used to save that file or folder to another user's Dropbox by passing it to copy_reference/save.

URL Structure
https://api.dropboxapi.com/2/files/copy_reference/get
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy_reference/get \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/video.mp4\"}"
Parameters
{
    "path": "/video.mp4"
}
GetCopyReferenceArg
pathString(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")The path to the file or folder you want to get a copy reference to.
Returns
{
    "copy_reference": "z1X6ATl6aWtzOGq0c3g5Ng",
    "expires": "2045-05-12T15:50:38Z",
    "metadata": {
        ".tag": "file",
        "client_modified": "2015-05-12T15:50:38Z",
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "file_lock_info": {
            "created": "2015-05-12T15:50:38Z",
            "is_lockholder": true,
            "lockholder_name": "Imaginary User"
        },
        "has_explicit_shared_members": false,
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "is_downloadable": true,
        "name": "Prime_Numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "path_lower": "/homework/math/prime_numbers.txt",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "rev": "a1c10ce0dd78",
        "server_modified": "2015-05-12T15:50:38Z",
        "sharing_info": {
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "parent_shared_folder_id": "84528192421",
            "read_only": true
        },
        "size": 7212
    }
}
GetCopyReferenceResult
metadataMetadata of the file or folder.
copy_referenceStringA copy reference to the file or folder.
expiresTimestamp(format="%Y-%m-%dT%H:%M:%SZ")The expiration date of the copy reference. This value is currently set to be far enough in the future so that expiration is effectively not an issue.
Errors
GetCopyReferenceError (open union)
path
See also general errors.

/copy_reference/save


Description

Save a copy reference returned by copy_reference/get to the user's Dropbox.

URL Structure
https://api.dropboxapi.com/2/files/copy_reference/save
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy_reference/save \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"copy_reference\":\"z1X6ATl6aWtzOGq0c3g5Ng\",\"path\":\"/video.mp4\"}"
Parameters
{
    "copy_reference": "z1X6ATl6aWtzOGq0c3g5Ng",
    "path": "/video.mp4"
}
SaveCopyReferenceArg
copy_referenceStringA copy reference returned by copy_reference/get.
pathString(pattern="/(.|[\r\n])*")Path in the user's Dropbox that is the destination.
Returns
{
    "metadata": {
        ".tag": "file",
        "client_modified": "2015-05-12T15:50:38Z",
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "file_lock_info": {
            "created": "2015-05-12T15:50:38Z",
            "is_lockholder": true,
            "lockholder_name": "Imaginary User"
        },
        "has_explicit_shared_members": false,
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "is_downloadable": true,
        "name": "Prime_Numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "path_lower": "/homework/math/prime_numbers.txt",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "rev": "a1c10ce0dd78",
        "server_modified": "2015-05-12T15:50:38Z",
        "sharing_info": {
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "parent_shared_folder_id": "84528192421",
            "read_only": true
        },
        "size": 7212
    }
}
SaveCopyReferenceResult
metadataThe metadata of the saved file or folder in the user's Dropbox.
Errors
Example: invalid_copy_reference
{
    "error": {
        ".tag": "invalid_copy_reference"
    },
    "error_summary": "invalid_copy_reference/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: not_found
{
    "error": {
        ".tag": "not_found"
    },
    "error_summary": "not_found/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SaveCopyReferenceError (open union)
path
invalid_copy_referenceVoidThe copy reference is invalid.
no_permissionVoidYou don't have permission to save the given copy reference. Please make sure this app is same app which created the copy reference and the source user is still linked to the app.
not_foundVoidThe file referenced by the copy reference cannot be found.
too_many_filesVoidThe operation would involve more than 10,000 files and folders.
See also general errors.

/create_folder


Description

Create a folder at a given path.

URL Structure
https://api.dropboxapi.com/2/files/create_folder_v2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/create_folder_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"autorename\":false,\"path\":\"/Homework/math\"}"
Parameters
{
    "autorename": false,
    "path": "/Homework/math"
}
CreateFolderArg
pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)")Path in the user's Dropbox to create.
autorenameBooleanIf there's a conflict, have the Dropbox server try to autorename the folder to avoid the conflict. The default for this field is False.
Returns
{
    "metadata": {
        "id": "id:a4ayc_80_OEAAAAAAAAAXz",
        "name": "math",
        "path_display": "/Homework/math",
        "path_lower": "/homework/math",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "sharing_info": {
            "no_access": false,
            "parent_shared_folder_id": "84528192421",
            "read_only": false,
            "traverse_only": false
        }
    }
}
CreateFolderResult
metadataMetadata of the created folder.
Errors
CreateFolderError (union)
path
See also general errors.

/create_folder_batch


Description

Create multiple folders at once. This route is asynchronous for large batches, which returns a job ID immediately and runs the create folder batch asynchronously. Otherwise, creates the folders and returns the result synchronously for smaller inputs. You can force asynchronous behaviour by using the CreateFolderBatchArg.force_async flag. Use create_folder_batch/check to check the job status.

URL Structure
https://api.dropboxapi.com/2/files/create_folder_batch
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/create_folder_batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"autorename\":false,\"force_async\":false,\"paths\":[\"/Homework/math\"]}"
Parameters
{
    "autorename": false,
    "force_async": false,
    "paths": [
        "/Homework/math"
    ]
}
CreateFolderBatchArg
paths List of (String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)"), max_items=10000)List of paths to be created in the user's Dropbox. Duplicate path arguments in the batch are considered only once.
autorenameBooleanIf there's a conflict, have the Dropbox server try to autorename the folder to avoid the conflict. The default for this field is False.
force_asyncBooleanWhether to force the create to happen asynchronously. The default for this field is False.
Returns
Example: complete
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "metadata": {
                "id": "id:a4ayc_80_OEAAAAAAAAAXz",
                "name": "math",
                "path_display": "/Homework/math",
                "path_lower": "/homework/math",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "sharing_info": {
                    "no_access": false,
                    "parent_shared_folder_id": "84528192421",
                    "read_only": false,
                    "traverse_only": false
                }
            }
        }
    ]
}
Example: async_job_id
{
    ".tag": "async_job_id",
    "async_job_id": "34g93hh34h04y384084"
}
Example: other
{
    ".tag": "other"
}
CreateFolderBatchLaunch (open union)
Result returned by create_folder_batch that may either launch an asynchronous job or complete synchronously.
async_job_idString(min_length=1)This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
complete
Errors
No endpoint-specific errors.
See also general errors.

/create_folder_batch/check


Description

Returns the status of an asynchronous job for create_folder_batch. If success, it returns list of result for each entry.

URL Structure
https://api.dropboxapi.com/2/files/create_folder_batch/check
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/create_folder_batch/check \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"async_job_id\":\"34g93hh34h04y384084\"}"
Parameters
{
    "async_job_id": "34g93hh34h04y384084"
}
PollArg
Arguments for methods that poll the status of an asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Returns
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "metadata": {
                "id": "id:a4ayc_80_OEAAAAAAAAAXz",
                "name": "math",
                "path_display": "/Homework/math",
                "path_lower": "/homework/math",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "sharing_info": {
                    "no_access": false,
                    "parent_shared_folder_id": "84528192421",
                    "read_only": false,
                    "traverse_only": false
                }
            }
        }
    ]
}
Example: in_progress
{
    ".tag": "in_progress"
}
Example: other
{
    ".tag": "other"
}
CreateFolderBatchJobStatus (open union)
in_progressVoidThe asynchronous job is still in progress.
completeThe batch create folder has finished.
failedThe batch create folder has failed.
Errors
Example: invalid_async_job_id
{
    "error": {
        ".tag": "invalid_async_job_id"
    },
    "error_summary": "invalid_async_job_id/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
PollError (open union)
Error returned by methods for polling the status of asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
invalid_async_job_idVoidThe job ID is invalid.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/delete


Description

Delete the file or folder at a given path. If the path is a folder, all its contents will be deleted too. A successful response indicates that the file or folder was deleted. The returned metadata will be the corresponding FileMetadata or FolderMetadata for the item at time of deletion, and not a DeletedMetadata object.

URL Structure
https://api.dropboxapi.com/2/files/delete_v2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/delete_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/Homework/math/Prime_Numbers.txt\"}"
Parameters
{
    "path": "/Homework/math/Prime_Numbers.txt"
}
DeleteArg
pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)")Path in the user's Dropbox to delete.
parent_rev String(min_length=9, pattern="[0-9a-f]+")?Perform delete if given "rev" matches the existing file's latest "rev". This field does not support deleting a folder. This field is optional.
Returns
{
    "metadata": {
        ".tag": "file",
        "client_modified": "2015-05-12T15:50:38Z",
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "file_lock_info": {
            "created": "2015-05-12T15:50:38Z",
            "is_lockholder": true,
            "lockholder_name": "Imaginary User"
        },
        "has_explicit_shared_members": false,
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "is_downloadable": true,
        "name": "Prime_Numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "path_lower": "/homework/math/prime_numbers.txt",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "rev": "a1c10ce0dd78",
        "server_modified": "2015-05-12T15:50:38Z",
        "sharing_info": {
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "parent_shared_folder_id": "84528192421",
            "read_only": true
        },
        "size": 7212
    }
}
DeleteResult
metadataMetadata of the deleted object.
Errors
Example: too_many_write_operations
{
    "error": {
        ".tag": "too_many_write_operations"
    },
    "error_summary": "too_many_write_operations/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
DeleteError (open union)
path_lookup
path_write
too_many_write_operationsVoidThere are too many write operations in user's Dropbox. Please retry this request.
too_many_filesVoidThere are too many files in one request. Please retry with fewer files.
See also general errors.

/delete_batch


Description

Delete multiple files/folders at once. This route is asynchronous, which returns a job ID immediately and runs the delete batch asynchronously. Use delete_batch/check to check the job status.

URL Structure
https://api.dropboxapi.com/2/files/delete_batch
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/delete_batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"entries\":[{\"path\":\"/Homework/math/Prime_Numbers.txt\"}]}"
Parameters
{
    "entries": [
        {
            "path": "/Homework/math/Prime_Numbers.txt"
        }
    ]
}
DeleteBatchArg
entriesList of (, max_items=1000)
Returns
Example: complete
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "metadata": {
                ".tag": "file",
                "client_modified": "2015-05-12T15:50:38Z",
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "file_lock_info": {
                    "created": "2015-05-12T15:50:38Z",
                    "is_lockholder": true,
                    "lockholder_name": "Imaginary User"
                },
                "has_explicit_shared_members": false,
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "is_downloadable": true,
                "name": "Prime_Numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "path_lower": "/homework/math/prime_numbers.txt",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "rev": "a1c10ce0dd78",
                "server_modified": "2015-05-12T15:50:38Z",
                "sharing_info": {
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "parent_shared_folder_id": "84528192421",
                    "read_only": true
                },
                "size": 7212
            }
        }
    ]
}
Example: async_job_id
{
    ".tag": "async_job_id",
    "async_job_id": "34g93hh34h04y384084"
}
Example: other
{
    ".tag": "other"
}
DeleteBatchLaunch (open union)
Result returned by delete_batch that may either launch an asynchronous job or complete synchronously.
async_job_idString(min_length=1)This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
complete
Errors
No endpoint-specific errors.
See also general errors.

/delete_batch/check


Description

Returns the status of an asynchronous job for delete_batch. If success, it returns list of result for each entry.

URL Structure
https://api.dropboxapi.com/2/files/delete_batch/check
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/delete_batch/check \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"async_job_id\":\"34g93hh34h04y384084\"}"
Parameters
{
    "async_job_id": "34g93hh34h04y384084"
}
PollArg
Arguments for methods that poll the status of an asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Returns
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "metadata": {
                ".tag": "file",
                "client_modified": "2015-05-12T15:50:38Z",
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "file_lock_info": {
                    "created": "2015-05-12T15:50:38Z",
                    "is_lockholder": true,
                    "lockholder_name": "Imaginary User"
                },
                "has_explicit_shared_members": false,
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "is_downloadable": true,
                "name": "Prime_Numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "path_lower": "/homework/math/prime_numbers.txt",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "rev": "a1c10ce0dd78",
                "server_modified": "2015-05-12T15:50:38Z",
                "sharing_info": {
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "parent_shared_folder_id": "84528192421",
                    "read_only": true
                },
                "size": 7212
            }
        }
    ]
}
Example: in_progress
{
    ".tag": "in_progress"
}
Example: other
{
    ".tag": "other"
}
DeleteBatchJobStatus (open union)
in_progressVoidThe asynchronous job is still in progress.
completeThe batch delete has finished.
failedThe batch delete has failed.
Errors
Example: invalid_async_job_id
{
    "error": {
        ".tag": "invalid_async_job_id"
    },
    "error_summary": "invalid_async_job_id/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
PollError (open union)
Error returned by methods for polling the status of asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
invalid_async_job_idVoidThe job ID is invalid.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/download


Description

Download a file from a user's Dropbox.

URL Structure
https://content.dropboxapi.com/2/files/download
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
Content-download
Required Scope
files.content.read
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/download \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"path\":\"/Homework/math/Prime_Numbers.txt\"}"
Parameters
{
    "path": "/Homework/math/Prime_Numbers.txt"
}
Example: id
{
    "path": "id:a4ayc_80_OEAAAAAAAAAYa"
}
Example: rev
{
    "path": "rev:a1c10ce0dd78"
}
DownloadArg
pathString(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")The path of the file to download.
revdeprecated String(min_length=9, pattern="[0-9a-f]+")?Field is deprecated. Please specify revision in path instead. This field is optional.
Returns
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "file_lock_info": {
        "created": "2015-05-12T15:50:38Z",
        "is_lockholder": true,
        "lockholder_name": "Imaginary User"
    },
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
Example: search_file_metadata
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
FileMetadata
nameStringThe last component of the path (including extension). This never contains a slash.
idString(min_length=1)A unique identifier for the file.
client_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")For files, this is the modification time set by the desktop client when the file was added to Dropbox. Since this time is not verified (the Dropbox server stores whatever the desktop client sends up), this should only be used for display purposes (such as sorting) and not, for example, to determine if a file has changed or not.
server_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")The last time the file was modified on Dropbox.
revString(min_length=9, pattern="[0-9a-f]+")A unique identifier for the current revision of a file. This field is the same rev as elsewhere in the API and can be used to detect changes and avoid conflicts.
sizeUInt64The file size in bytes.
path_lower String?The lowercased full path in the user's Dropbox. This always starts with a slash. This field will be null if the file or folder is not mounted. This field is optional.
path_display String?The cased path to be used for display purposes only. In rare instances the casing will not correctly match the user's filesystem, but this behavior will match the path provided in the Core API v1, and at least the last path component will have the correct casing. Changes to only the casing of paths won't be returned by list_folder/continue. This field will be null if the file or folder is not mounted. This field is optional.
parent_shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")?Field is deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
preview_url String?The preview URL of the file. This field is optional.
media_info?Additional information if the file is a photo or video. This field will not be set on entries returned by list_folder, list_folder/continue, or get_thumbnail_batch, starting December 2, 2019. This field is optional.
symlink_info?Set if this file is a symlink. This field is optional.
sharing_info?Set if this file is contained in a shared folder. This field is optional.
is_downloadableBooleanIf true, file can be downloaded directly; else the file must be exported. The default for this field is True.
export_info?Information about format this file can be exported to. This filed must be set if is_downloadable is set to false. This field is optional.
property_groupsList of ()?Additional information if the file has custom properties with the property template specified. This field is optional.
has_explicit_shared_members Boolean?This flag will only be present if include_has_explicit_shared_members is true in list_folder or get_metadata. If this flag is present, it will be true if this file has any explicit shared members. This is different from sharing_info in that this could be true in the case where a file has explicit members but is not contained within a shared folder. This field is optional.
content_hash String(min_length=64, max_length=64)?A hash of the file content. This field can be used to verify data integrity. For more information see our Content hash page. This field is optional.
file_lock_info?If present, the metadata associated with the file's current lock. This field is optional.
Errors
Example: unsupported_file
{
    "error": {
        ".tag": "unsupported_file"
    },
    "error_summary": "unsupported_file/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
DownloadError (open union)
path
unsupported_fileVoidThis file type cannot be downloaded directly; use export instead.
See also general errors.

/download_zip


Description

Download a folder from the user's Dropbox, as a zip file. The folder must be less than 20 GB in size and any single file within must be less than 4 GB in size. The resulting zip must have fewer than 10,000 total file and folder entries, including the top level folder. The input cannot be a single file. Note: this endpoint does not support HTTP range requests.

URL Structure
https://content.dropboxapi.com/2/files/download_zip
Authentication
User Authentication
Endpoint format
Content-download
Required Scope
files.content.read
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/download_zip \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"path\":\"/Homework/math\"}"
Parameters
{
    "path": "/Homework/math"
}
Example: id
{
    "path": "id:a4ayc_80_OEAAAAAAAAAYa"
}
Example: rev
{
    "path": "rev:a1c10ce0dd78"
}
DownloadZipArg
pathString(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")The path of the folder to download.
Returns
{
    "metadata": {
        "id": "id:a4ayc_80_OEAAAAAAAAAXz",
        "name": "math",
        "path_display": "/Homework/math",
        "path_lower": "/homework/math",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "sharing_info": {
            "no_access": false,
            "parent_shared_folder_id": "84528192421",
            "read_only": false,
            "traverse_only": false
        }
    }
}
DownloadZipResult
metadata
Errors
Example: too_large
{
    "error": {
        ".tag": "too_large"
    },
    "error_summary": "too_large/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
DownloadZipError (open union)
path
too_largeVoidThe folder or a file is too large to download.
too_many_filesVoidThe folder has too many files to download.
See also general errors.

/export


PREVIEW - may change or disappear without notice
Description

Export a file from a user's Dropbox. This route only supports exporting files that cannot be downloaded directly and whose ExportResult.file_metadata has ExportInfo.export_as populated.

URL Structure
https://content.dropboxapi.com/2/files/export
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
Content-download
Required Scope
files.content.read
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/export \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"path\":\"/Homework/math/Prime_Numbers.gsheet\"}"
Parameters
{
    "path": "/Homework/math/Prime_Numbers.gsheet"
}
Example: id
{
    "path": "id:a4ayc_80_OEAAAAAAAAAYa"
}
ExportArg
pathString(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")The path of the file to be exported.
export_format String?The file format to which the file should be exported. This must be one of the formats listed in the file's export_options returned by get_metadata. If none is specified, the default format (specified in export_as in file metadata) will be used. This field is optional.
Returns
{
    "export_metadata": {
        "export_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "name": "Prime_Numbers.xlsx",
        "size": 7189
    },
    "file_metadata": {
        "client_modified": "2015-05-12T15:50:38Z",
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "file_lock_info": {
            "created": "2015-05-12T15:50:38Z",
            "is_lockholder": true,
            "lockholder_name": "Imaginary User"
        },
        "has_explicit_shared_members": false,
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "is_downloadable": true,
        "name": "Prime_Numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "path_lower": "/homework/math/prime_numbers.txt",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "rev": "a1c10ce0dd78",
        "server_modified": "2015-05-12T15:50:38Z",
        "sharing_info": {
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "parent_shared_folder_id": "84528192421",
            "read_only": true
        },
        "size": 7212
    }
}
ExportResult
export_metadataMetadata for the exported version of the file.
file_metadataMetadata for the original file.
Errors
Example: non_exportable
{
    "error": {
        ".tag": "non_exportable"
    },
    "error_summary": "non_exportable/..."
}
Example: invalid_export_format
{
    "error": {
        ".tag": "invalid_export_format"
    },
    "error_summary": "invalid_export_format/..."
}
Example: retry_error
{
    "error": {
        ".tag": "retry_error"
    },
    "error_summary": "retry_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ExportError (open union)
path
non_exportableVoidThis file type cannot be exported. Use download instead.
invalid_export_formatVoidThe specified export format is not a valid option for this file type.
retry_errorVoidThe exportable content is not yet available. Please retry later.
See also general errors.

/get_file_lock_batch


Description

Return the lock metadata for the given list of paths.

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

URL Structure
https://api.dropboxapi.com/2/files/get_file_lock_batch
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.content.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/get_file_lock_batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"entries\":[{\"path\":\"/John Doe/sample/test.pdf\"}]}"
Parameters
{
    "entries": [
        {
            "path": "/John Doe/sample/test.pdf"
        }
    ]
}
LockFileBatchArg
entriesList of ()List of 'entries'. Each 'entry' contains a path of the file which will be locked or queried. Duplicate path arguments in the batch are considered only once.
Returns
{
    "entries": [
        {
            ".tag": "success",
            "lock": {
                "content": {
                    ".tag": "single_user",
                    "created": "2015-05-12T15:50:38Z",
                    "lock_holder_account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "lock_holder_team_id": "dbtid:1234abcd"
                }
            },
            "metadata": {
                ".tag": "file",
                "client_modified": "2015-05-12T15:50:38Z",
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "file_lock_info": {
                    "created": "2015-05-12T15:50:38Z",
                    "is_lockholder": true,
                    "lockholder_name": "Imaginary User"
                },
                "has_explicit_shared_members": false,
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "is_downloadable": true,
                "name": "Prime_Numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "path_lower": "/homework/math/prime_numbers.txt",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "rev": "a1c10ce0dd78",
                "server_modified": "2015-05-12T15:50:38Z",
                "sharing_info": {
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "parent_shared_folder_id": "84528192421",
                    "read_only": true
                },
                "size": 7212
            }
        }
    ]
}
LockFileBatchResult
entriesList of ()Each Entry in the 'entries' will have '.tag' with the operation status (e.g. success), the metadata for the file and the lock state after the operation.
Errors
Example: too_many_write_operations
{
    "error": {
        ".tag": "too_many_write_operations"
    },
    "error_summary": "too_many_write_operations/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: no_write_permission
{
    "error": {
        ".tag": "no_write_permission"
    },
    "error_summary": "no_write_permission/..."
}
Example: cannot_be_locked
{
    "error": {
        ".tag": "cannot_be_locked"
    },
    "error_summary": "cannot_be_locked/..."
}
Example: file_not_shared
{
    "error": {
        ".tag": "file_not_shared"
    },
    "error_summary": "file_not_shared/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
LockFileError (open union)
path_lookupCould not find the specified resource.
too_many_write_operationsVoidThere are too many write operations in user's Dropbox. Please retry this request.
too_many_filesVoidThere are too many files in one request. Please retry with fewer files.
no_write_permissionVoidThe user does not have permissions to change the lock state or access the file.
cannot_be_lockedVoidItem is a type that cannot be locked.
file_not_sharedVoidRequested file is not currently shared.
lock_conflictThe user action conflicts with an existing lock on the file.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/get_metadata


Description

Returns the metadata for a file or folder. Note: Metadata for the root folder is unsupported.

URL Structure
https://api.dropboxapi.com/2/files/get_metadata
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/get_metadata \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"include_deleted\":false,\"include_has_explicit_shared_members\":false,\"include_media_info\":false,\"path\":\"/Homework/math\"}"
Parameters
{
    "include_deleted": false,
    "include_has_explicit_shared_members": false,
    "include_media_info": false,
    "path": "/Homework/math"
}
Example: id
{
    "include_deleted": false,
    "include_has_explicit_shared_members": false,
    "include_media_info": false,
    "path": "id:a4ayc_80_OEAAAAAAAAAYa"
}
Example: rev
{
    "include_deleted": false,
    "include_has_explicit_shared_members": false,
    "include_media_info": false,
    "path": "rev:a1c10ce0dd78"
}
GetMetadataArg
pathString(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")The path of a file or folder on Dropbox.
include_media_infoBooleanIf true, FileMetadata.media_info is set for photo and video. The default for this field is False.
include_deletedBooleanIf true, DeletedMetadata will be returned for deleted file or folder, otherwise LookupError.not_found will be returned. The default for this field is False.
include_has_explicit_shared_membersBooleanIf true, the results will include a flag for each file indicating whether or not that file has any explicit members. The default for this field is False.
include_property_groups?If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates. This field is optional.
Returns
{
    ".tag": "file",
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "file_lock_info": {
        "created": "2015-05-12T15:50:38Z",
        "is_lockholder": true,
        "lockholder_name": "Imaginary User"
    },
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
{
    ".tag": "folder",
    "id": "id:a4ayc_80_OEAAAAAAAAAXz",
    "name": "math",
    "path_display": "/Homework/math",
    "path_lower": "/homework/math",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "sharing_info": {
        "no_access": false,
        "parent_shared_folder_id": "84528192421",
        "read_only": false,
        "traverse_only": false
    }
}
Example: search_file_metadata
{
    ".tag": "file",
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
Metadata (datatype with subtypes)
Metadata for a file or folder.
file
folder
deleted
Errors
GetMetadataError (union)
path
See also general errors.

/get_preview


Description

Get a preview for a file. Currently, PDF previews are generated for files with the following extensions: .ai, .doc, .docm, .docx, .eps, .gdoc, .gslides, .odp, .odt, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .rtf. HTML previews are generated for files with the following extensions: .csv, .ods, .xls, .xlsm, .gsheet, .xlsx. Other formats will return an unsupported extension error.

URL Structure
https://content.dropboxapi.com/2/files/get_preview
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
Content-download
Required Scope
files.content.read
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/get_preview \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"path\":\"/word.docx\"}"
Parameters
{
    "path": "/word.docx"
}
Example: id
{
    "path": "id:a4ayc_80_OEAAAAAAAAAYa"
}
Example: rev
{
    "path": "rev:a1c10ce0dd78"
}
PreviewArg
pathString(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")The path of the file to preview.
revdeprecated String(min_length=9, pattern="[0-9a-f]+")?Field is deprecated. Please specify revision in path instead. This field is optional.
Returns
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "file_lock_info": {
        "created": "2015-05-12T15:50:38Z",
        "is_lockholder": true,
        "lockholder_name": "Imaginary User"
    },
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
Example: search_file_metadata
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
FileMetadata
nameStringThe last component of the path (including extension). This never contains a slash.
idString(min_length=1)A unique identifier for the file.
client_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")For files, this is the modification time set by the desktop client when the file was added to Dropbox. Since this time is not verified (the Dropbox server stores whatever the desktop client sends up), this should only be used for display purposes (such as sorting) and not, for example, to determine if a file has changed or not.
server_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")The last time the file was modified on Dropbox.
revString(min_length=9, pattern="[0-9a-f]+")A unique identifier for the current revision of a file. This field is the same rev as elsewhere in the API and can be used to detect changes and avoid conflicts.
sizeUInt64The file size in bytes.
path_lower String?The lowercased full path in the user's Dropbox. This always starts with a slash. This field will be null if the file or folder is not mounted. This field is optional.
path_display String?The cased path to be used for display purposes only. In rare instances the casing will not correctly match the user's filesystem, but this behavior will match the path provided in the Core API v1, and at least the last path component will have the correct casing. Changes to only the casing of paths won't be returned by list_folder/continue. This field will be null if the file or folder is not mounted. This field is optional.
parent_shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")?Field is deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
preview_url String?The preview URL of the file. This field is optional.
media_info?Additional information if the file is a photo or video. This field will not be set on entries returned by list_folder, list_folder/continue, or get_thumbnail_batch, starting December 2, 2019. This field is optional.
symlink_info?Set if this file is a symlink. This field is optional.
sharing_info?Set if this file is contained in a shared folder. This field is optional.
is_downloadableBooleanIf true, file can be downloaded directly; else the file must be exported. The default for this field is True.
export_info?Information about format this file can be exported to. This filed must be set if is_downloadable is set to false. This field is optional.
property_groupsList of ()?Additional information if the file has custom properties with the property template specified. This field is optional.
has_explicit_shared_members Boolean?This flag will only be present if include_has_explicit_shared_members is true in list_folder or get_metadata. If this flag is present, it will be true if this file has any explicit shared members. This is different from sharing_info in that this could be true in the case where a file has explicit members but is not contained within a shared folder. This field is optional.
content_hash String(min_length=64, max_length=64)?A hash of the file content. This field can be used to verify data integrity. For more information see our Content hash page. This field is optional.
file_lock_info?If present, the metadata associated with the file's current lock. This field is optional.
Errors
Example: in_progress
{
    "error": {
        ".tag": "in_progress"
    },
    "error_summary": "in_progress/..."
}
Example: unsupported_extension
{
    "error": {
        ".tag": "unsupported_extension"
    },
    "error_summary": "unsupported_extension/..."
}
Example: unsupported_content
{
    "error": {
        ".tag": "unsupported_content"
    },
    "error_summary": "unsupported_content/..."
}
PreviewError (union)
pathAn error occurs when downloading metadata for the file.
in_progressVoidThis preview generation is still in progress and the file is not ready for preview yet.
unsupported_extensionVoidThe file extension is not supported preview generation.
unsupported_contentVoidThe file content is not supported for preview generation.
See also general errors.

/get_temporary_link


Description

Get a temporary link to stream content of a file. This link will expire in four hours and afterwards you will get 410 Gone. This URL should not be used to display content directly in the browser. The Content-Type of the link is determined automatically by the file's mime type.

URL Structure
https://api.dropboxapi.com/2/files/get_temporary_link
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.content.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/get_temporary_link \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/video.mp4\"}"
Parameters
{
    "path": "/video.mp4"
}
GetTemporaryLinkArg
pathString(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")The path to the file you want a temporary link to.
Returns
{
    "link": "https://ucabc123456.dl.dropboxusercontent.com/cd/0/get/abcdefghijklmonpqrstuvwxyz1234567890/file",
    "metadata": {
        "client_modified": "2015-05-12T15:50:38Z",
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "file_lock_info": {
            "created": "2015-05-12T15:50:38Z",
            "is_lockholder": true,
            "lockholder_name": "Imaginary User"
        },
        "has_explicit_shared_members": false,
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "is_downloadable": true,
        "name": "Prime_Numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "path_lower": "/homework/math/prime_numbers.txt",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "rev": "a1c10ce0dd78",
        "server_modified": "2015-05-12T15:50:38Z",
        "sharing_info": {
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "parent_shared_folder_id": "84528192421",
            "read_only": true
        },
        "size": 7212
    }
}
GetTemporaryLinkResult
metadataMetadata of the file.
linkStringThe temporary link which can be used to stream content the file.
Errors
Example: email_not_verified
{
    "error": {
        ".tag": "email_not_verified"
    },
    "error_summary": "email_not_verified/..."
}
Example: unsupported_file
{
    "error": {
        ".tag": "unsupported_file"
    },
    "error_summary": "unsupported_file/..."
}
Example: not_allowed
{
    "error": {
        ".tag": "not_allowed"
    },
    "error_summary": "not_allowed/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
GetTemporaryLinkError (open union)
path
email_not_verifiedVoidThis user's email address is not verified. This functionality is only available on accounts with a verified email address. Users can verify their email address here.
unsupported_fileVoidCannot get temporary link to this file type; use export instead.
not_allowedVoidThe user is not allowed to request a temporary link to the specified file. For example, this can occur if the file is restricted or if the user's links are banned.
See also general errors.

/get_temporary_upload_link


Description

Get a one-time use temporary upload link to upload a file to a Dropbox location. This endpoint acts as a delayed upload. The returned temporary upload link may be used to make a POST request with the data to be uploaded. The upload will then be perfomed with the CommitInfo previously provided to get_temporary_upload_link but evaluated only upon consumption. Hence, errors stemming from invalid CommitInfo with respect to the state of the user's Dropbox will only be communicated at consumption time. Additionally, these errors are surfaced as generic HTTP 409 Conflict responses, potentially hiding issue details. The maximum temporary upload link duration is 4 hours. Upon consumption or expiration, a new link will have to be generated. Multiple links may exist for a specific upload path at any given time. The POST request on the temporary upload link must have its Content-Type set to "application/octet-stream". Example temporary upload link consumption request: curl -X POST https://content.dropboxapi.com/apitul/1/bNi2uIYF51cVBND --header "Content-Type: application/octet-stream" --data-binary @local_file.txt A successful temporary upload link consumption request returns the content hash of the uploaded data in JSON format. Example successful temporary upload link consumption response: {"content-hash": "599d71033d700ac892a0e48fa61b125d2f5994"} An unsuccessful temporary upload link consumption request returns any of the following status codes: HTTP 400 Bad Request: Content-Type is not one of application/octet-stream and text/plain or request is invalid. HTTP 409 Conflict: The temporary upload link does not exist or is currently unavailable, the upload failed, or another error happened. HTTP 410 Gone: The temporary upload link is expired or consumed. Example unsuccessful temporary upload link consumption response: Temporary upload link has been recently consumed.

URL Structure
https://api.dropboxapi.com/2/files/get_temporary_upload_link
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/get_temporary_upload_link \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"commit_info\":{\"autorename\":true,\"mode\":\"add\",\"mute\":false,\"path\":\"/Homework/math/Matrices.txt\",\"strict_conflict\":false},\"duration\":3600}"
Parameters
{
    "commit_info": {
        "autorename": true,
        "mode": "add",
        "mute": false,
        "path": "/Homework/math/Matrices.txt",
        "strict_conflict": false
    },
    "duration": 3600
}
GetTemporaryUploadLinkArg
commit_infoContains the path and other optional modifiers for the future upload commit. Equivalent to the parameters provided to upload.
durationFloat64(min=60.0, max=14400.0)How long before this link expires, in seconds. Attempting to start an upload with this link longer than this period of time after link creation will result in an error. The default for this field is 14400.0.
Returns
{
    "link": "https://content.dropboxapi.com/apitul/1/bNi2uIYF51cVBND"
}
GetTemporaryUploadLinkResult
linkStringThe temporary link which can be used to stream a file to a Dropbox location.
Errors
No endpoint-specific errors.
See also general errors.

/get_thumbnail


Description

Get a thumbnail for an image. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif, webp, ppm and bmp. Photos that are larger than 20MB in size won't be converted to a thumbnail.

URL Structure
https://content.dropboxapi.com/2/files/get_thumbnail_v2
Authentication
User Authentication, App Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
Content-download
Required Scope
files.content.read
Example
Get app key and secret for:
curl -X POST https://content.dropboxapi.com/2/files/get_thumbnail_v2 \
    --header "Authorization: Basic <get app key and secret>" \
    --header "Dropbox-API-Arg: {\"format\":\"jpeg\",\"mode\":\"strict\",\"quality\":\"quality_80\",\"resource\":{\".tag\":\"path\",\"path\":\"/a.docx\"},\"size\":\"w64h64\"}"
Parameters
{
    "format": "jpeg",
    "mode": "strict",
    "quality": "quality_80",
    "resource": {
        ".tag": "path",
        "path": "/a.docx"
    },
    "size": "w64h64"
}
ThumbnailV2Arg
resourceInformation specifying which file to preview. This could be a path to a file, a shared link pointing to a file, or a shared link pointing to a folder, with a relative path.
formatThe format for the thumbnail image, jpeg (default), png, or webp. For images that are photos, jpeg should be preferred, while png is better for screenshots and digital arts, and web for compression. The default for this union is jpeg.
sizeThe size for the thumbnail image. The default for this union is w64h64.
modeHow to resize and crop the image to achieve the desired size. The default for this union is strict.
qualityinternalField is only returned for "internal" callers. Quality of the thumbnail image. The default for this union is quality_80.
exclude_media_info Boolean?Normally, FileMetadata.media_info is set for photo and video. When this flag is true, FileMetadata.media_info is not populated. This improves latency for use cases where `media_info` is not needed. This field is optional.
Returns
{
    "file_metadata": {
        "client_modified": "2015-05-12T15:50:38Z",
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "file_lock_info": {
            "created": "2015-05-12T15:50:38Z",
            "is_lockholder": true,
            "lockholder_name": "Imaginary User"
        },
        "has_explicit_shared_members": false,
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "is_downloadable": true,
        "name": "Prime_Numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "path_lower": "/homework/math/prime_numbers.txt",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "rev": "a1c10ce0dd78",
        "server_modified": "2015-05-12T15:50:38Z",
        "sharing_info": {
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "parent_shared_folder_id": "84528192421",
            "read_only": true
        },
        "size": 7212
    }
}
PreviewResult
file_metadata?Metadata corresponding to the file received as an argument. Will be populated if the endpoint is called with a path (ReadPath). This field is optional.
link_metadata?Minimal metadata corresponding to the file received as an argument. Will be populated if the endpoint is called using a shared link (SharedLinkFileInfo). This field is optional.
Errors
Example: unsupported_extension
{
    "error": {
        ".tag": "unsupported_extension"
    },
    "error_summary": "unsupported_extension/..."
}
Example: unsupported_image
{
    "error": {
        ".tag": "unsupported_image"
    },
    "error_summary": "unsupported_image/..."
}
Example: encrypted_content
{
    "error": {
        ".tag": "encrypted_content"
    },
    "error_summary": "encrypted_content/..."
}
Example: conversion_error
{
    "error": {
        ".tag": "conversion_error"
    },
    "error_summary": "conversion_error/..."
}
Example: access_denied
{
    "error": {
        ".tag": "access_denied"
    },
    "error_summary": "access_denied/..."
}
Example: not_found
{
    "error": {
        ".tag": "not_found"
    },
    "error_summary": "not_found/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ThumbnailV2Error (open union)
pathAn error occurred when downloading metadata for the image.
unsupported_extensionVoidThe file extension doesn't allow conversion to a thumbnail.
unsupported_imageVoidThe image cannot be converted to a thumbnail.
encrypted_contentVoidEncrypted content cannot be converted to a thumbnail.
conversion_errorVoidAn error occurred during thumbnail conversion.
access_deniedVoidAccess to this shared link is forbidden.
not_foundVoidThe shared link does not exist.
See also general errors.

/get_thumbnail_batch


Description

Get thumbnails for a list of images. We allow up to 25 thumbnails in a single batch. This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif, webp, ppm and bmp. Photos that are larger than 20MB in size won't be converted to a thumbnail.

URL Structure
https://content.dropboxapi.com/2/files/get_thumbnail_batch
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
files.content.read
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/get_thumbnail_batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"entries\":[{\"format\":\"jpeg\",\"mode\":\"strict\",\"path\":\"/image.jpg\",\"quality\":\"quality_80\",\"size\":\"w64h64\"}]}"
Parameters
{
    "entries": [
        {
            "format": "jpeg",
            "mode": "strict",
            "path": "/image.jpg",
            "quality": "quality_80",
            "size": "w64h64"
        }
    ]
}
GetThumbnailBatchArg
Arguments for get_thumbnail_batch.
entriesList of ()List of files to get thumbnails.
Returns
{
    "entries": [
        {
            ".tag": "success",
            "metadata": {
                "client_modified": "2015-05-12T15:50:38Z",
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "file_lock_info": {
                    "created": "2015-05-12T15:50:38Z",
                    "is_lockholder": true,
                    "lockholder_name": "Imaginary User"
                },
                "has_explicit_shared_members": false,
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "is_downloadable": true,
                "name": "Prime_Numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "path_lower": "/homework/math/prime_numbers.txt",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "rev": "a1c10ce0dd78",
                "server_modified": "2015-05-12T15:50:38Z",
                "sharing_info": {
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "parent_shared_folder_id": "84528192421",
                    "read_only": true
                },
                "size": 7212
            },
            "thumbnail": "iVBORw0KGgoAAAANSUhEUgAAAdcAAABrCAMAAAI="
        }
    ]
}
GetThumbnailBatchResult
entriesList of ()List of files and their thumbnails.
Errors
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
GetThumbnailBatchError (open union)
too_many_filesVoidThe operation involves more than 25 files.
See also general errors.

/list_folder


Description

Starts returning the contents of a folder. If the result's ListFolderResult.has_more field is true, call list_folder/continue with the returned ListFolderResult.cursor to retrieve more entries. If you're using ListFolderArg.recursive set to true to keep a local cache of the contents of a Dropbox account, iterate through each entry in order and process them as follows to keep your local state in sync: For each FileMetadata, store the new entry at the given path in your local state. If the required parent folders don't exist yet, create them. If there's already something else at the given path, replace it and remove all its children. For each FolderMetadata, store the new entry at the given path in your local state. If the required parent folders don't exist yet, create them. If there's already something else at the given path, replace it but leave the children as they are. Check the new entry's FolderSharingInfo.read_only and set all its children's read-only statuses to match. For each DeletedMetadata, if your local state has something at the given path, remove it and all its children. If there's nothing at the given path, ignore this entry. Note: auth.RateLimitError may be returned if multiple list_folder or list_folder/continue calls with same parameters are made simultaneously by same API app for same user. If your app implements retry logic, please hold off the retry until the previous request finishes.

URL Structure
https://api.dropboxapi.com/2/files/list_folder
Authentication
User Authentication, App Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get app key and secret for:
curl -X POST https://api.dropboxapi.com/2/files/list_folder \
    --header "Authorization: Basic <get app key and secret>" \
    --header "Content-Type: application/json" \
    --data "{\"include_deleted\":false,\"include_has_explicit_shared_members\":false,\"include_media_info\":false,\"include_mounted_folders\":true,\"include_non_downloadable_files\":true,\"path\":\"/Homework/math\",\"recursive\":false}"
Parameters
{
    "include_deleted": false,
    "include_has_explicit_shared_members": false,
    "include_media_info": false,
    "include_mounted_folders": true,
    "include_non_downloadable_files": true,
    "path": "/Homework/math",
    "recursive": false
}
ListFolderArg
pathString(pattern="(/(.|[\r\n])*)?|id:.*|(ns:[0-9]+(/.*)?)")A unique identifier for the file.
recursiveBooleanIf true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders. In some cases, setting ListFolderArg.recursive to true may lead to performance issues or errors, especially when traversing folder structures with a large number of items. A workaround for such cases is to set ListFolderArg.recursive to false and traverse subfolders one at a time. The default for this field is False.
include_media_infodeprecatedBooleanField is deprecated. If true, FileMetadata.media_info is set for photo and video. This parameter will no longer have an effect starting December 2, 2019. The default for this field is False.
include_deletedBooleanIf true, the results will include entries for files and folders that used to exist but were deleted. The default for this field is False.
include_has_explicit_shared_membersBooleanIf true, the results will include a flag for each file indicating whether or not that file has any explicit members. The default for this field is False.
include_mounted_foldersBooleanIf true, the results will include entries under mounted folders which includes app folder, shared folder and team folder. The default for this field is True.
limit UInt32(min=1, max=2000)?The maximum number of results to return per request. Note: This is an approximate number and there can be slightly more entries returned in some cases. This field is optional.
shared_link?A shared link to list the contents of. If the link is password-protected, the password must be provided. If this field is present, ListFolderArg.path will be relative to root of the shared link. Only non-recursive mode is supported for shared link. This field is optional.
include_property_groups?If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates. This field is optional.
include_non_downloadable_filesBooleanIf true, include files that are not downloadable, i.e. Google Docs. The default for this field is True.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "entries": [
        {
            ".tag": "file",
            "client_modified": "2015-05-12T15:50:38Z",
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "file_lock_info": {
                "created": "2015-05-12T15:50:38Z",
                "is_lockholder": true,
                "lockholder_name": "Imaginary User"
            },
            "has_explicit_shared_members": false,
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "is_downloadable": true,
            "name": "Prime_Numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "path_lower": "/homework/math/prime_numbers.txt",
            "property_groups": [
                {
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ],
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                }
            ],
            "rev": "a1c10ce0dd78",
            "server_modified": "2015-05-12T15:50:38Z",
            "sharing_info": {
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "parent_shared_folder_id": "84528192421",
                "read_only": true
            },
            "size": 7212
        },
        {
            ".tag": "folder",
            "id": "id:a4ayc_80_OEAAAAAAAAAXz",
            "name": "math",
            "path_display": "/Homework/math",
            "path_lower": "/homework/math",
            "property_groups": [
                {
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ],
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                }
            ],
            "sharing_info": {
                "no_access": false,
                "parent_shared_folder_id": "84528192421",
                "read_only": false,
                "traverse_only": false
            }
        }
    ],
    "has_more": false
}
ListFolderResult
entriesList of ()The files and (direct) subfolders in the folder.
cursorString(min_length=1)Pass the cursor into list_folder/continue to see what's changed in the folder since your previous query.
has_moreBooleanIf true, then there are more entries available. Pass the cursor to list_folder/continue to retrieve the rest.
Errors
ListFolderError (open union)
path
template_error
See also general errors.

/list_folder/continue


Description

Once a cursor has been retrieved from list_folder, use this to paginate through all files and retrieve updates to the folder, following the same rules as documented for list_folder.

URL Structure
https://api.dropboxapi.com/2/files/list_folder/continue
Authentication
User Authentication, App Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get app key and secret for:
curl -X POST https://api.dropboxapi.com/2/files/list_folder/continue \
    --header "Authorization: Basic <get app key and secret>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
ListFolderContinueArg
cursorString(min_length=1)The cursor returned by your last call to list_folder or list_folder/continue.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "entries": [
        {
            ".tag": "file",
            "client_modified": "2015-05-12T15:50:38Z",
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "file_lock_info": {
                "created": "2015-05-12T15:50:38Z",
                "is_lockholder": true,
                "lockholder_name": "Imaginary User"
            },
            "has_explicit_shared_members": false,
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "is_downloadable": true,
            "name": "Prime_Numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "path_lower": "/homework/math/prime_numbers.txt",
            "property_groups": [
                {
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ],
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                }
            ],
            "rev": "a1c10ce0dd78",
            "server_modified": "2015-05-12T15:50:38Z",
            "sharing_info": {
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "parent_shared_folder_id": "84528192421",
                "read_only": true
            },
            "size": 7212
        },
        {
            ".tag": "folder",
            "id": "id:a4ayc_80_OEAAAAAAAAAXz",
            "name": "math",
            "path_display": "/Homework/math",
            "path_lower": "/homework/math",
            "property_groups": [
                {
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ],
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                }
            ],
            "sharing_info": {
                "no_access": false,
                "parent_shared_folder_id": "84528192421",
                "read_only": false,
                "traverse_only": false
            }
        }
    ],
    "has_more": false
}
ListFolderResult
entriesList of ()The files and (direct) subfolders in the folder.
cursorString(min_length=1)Pass the cursor into list_folder/continue to see what's changed in the folder since your previous query.
has_moreBooleanIf true, then there are more entries available. Pass the cursor to list_folder/continue to retrieve the rest.
Errors
Example: reset
{
    "error": {
        ".tag": "reset"
    },
    "error_summary": "reset/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ListFolderContinueError (open union)
path
resetVoidIndicates that the cursor has been invalidated. Call list_folder to obtain a new cursor.
See also general errors.

/list_folder/get_latest_cursor


Description

A way to quickly get a cursor for the folder's state. Unlike list_folder, list_folder/get_latest_cursor doesn't return any entries. This endpoint is for app which only needs to know about new files and modifications and doesn't need to know about files that already exist in Dropbox.

URL Structure
https://api.dropboxapi.com/2/files/list_folder/get_latest_cursor
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/list_folder/get_latest_cursor \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"include_deleted\":false,\"include_has_explicit_shared_members\":false,\"include_media_info\":false,\"include_mounted_folders\":true,\"include_non_downloadable_files\":true,\"path\":\"/Homework/math\",\"recursive\":false}"
Parameters
{
    "include_deleted": false,
    "include_has_explicit_shared_members": false,
    "include_media_info": false,
    "include_mounted_folders": true,
    "include_non_downloadable_files": true,
    "path": "/Homework/math",
    "recursive": false
}
ListFolderArg
pathString(pattern="(/(.|[\r\n])*)?|id:.*|(ns:[0-9]+(/.*)?)")A unique identifier for the file.
recursiveBooleanIf true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders. In some cases, setting ListFolderArg.recursive to true may lead to performance issues or errors, especially when traversing folder structures with a large number of items. A workaround for such cases is to set ListFolderArg.recursive to false and traverse subfolders one at a time. The default for this field is False.
include_media_infodeprecatedBooleanField is deprecated. If true, FileMetadata.media_info is set for photo and video. This parameter will no longer have an effect starting December 2, 2019. The default for this field is False.
include_deletedBooleanIf true, the results will include entries for files and folders that used to exist but were deleted. The default for this field is False.
include_has_explicit_shared_membersBooleanIf true, the results will include a flag for each file indicating whether or not that file has any explicit members. The default for this field is False.
include_mounted_foldersBooleanIf true, the results will include entries under mounted folders which includes app folder, shared folder and team folder. The default for this field is True.
limit UInt32(min=1, max=2000)?The maximum number of results to return per request. Note: This is an approximate number and there can be slightly more entries returned in some cases. This field is optional.
shared_link?A shared link to list the contents of. If the link is password-protected, the password must be provided. If this field is present, ListFolderArg.path will be relative to root of the shared link. Only non-recursive mode is supported for shared link. This field is optional.
include_property_groups?If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates. This field is optional.
include_non_downloadable_filesBooleanIf true, include files that are not downloadable, i.e. Google Docs. The default for this field is True.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
ListFolderGetLatestCursorResult
cursorString(min_length=1)Pass the cursor into list_folder/continue to see what's changed in the folder since your previous query.
Errors
ListFolderError (open union)
path
template_error
See also general errors.

/list_folder/longpoll


Description

A longpoll endpoint to wait for changes on an account. In conjunction with list_folder/continue, this call gives you a low-latency way to monitor an account for file changes. The connection will block until there are changes available or a timeout occurs. This endpoint is useful mostly for client-side apps. If you're looking for server-side notifications, check out our webhooks documentation.

URL Structure
https://notify.dropboxapi.com/2/files/list_folder/longpoll
Authentication
No Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://notify.dropboxapi.com/2/files/list_folder/longpoll \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\",\"timeout\":30}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "timeout": 30
}
ListFolderLongpollArg
cursorString(min_length=1)A cursor as returned by list_folder or list_folder/continue. Cursors retrieved by setting ListFolderArg.include_media_info to true are not supported.
timeoutUInt64(min=30, max=480)A timeout in seconds. The request will block for at most this length of time, plus up to 90 seconds of random jitter added to avoid the thundering herd problem. Care should be taken when using this parameter, as some network infrastructure does not support long timeouts. The default for this field is 30.
Returns
{
    "changes": true
}
ListFolderLongpollResult
changesBooleanIndicates whether new changes are available. If true, call list_folder/continue to retrieve the changes.
backoff UInt64?If present, backoff for at least this many seconds before calling list_folder/longpoll again. This field is optional.
Errors
Example: reset
{
    "error": {
        ".tag": "reset"
    },
    "error_summary": "reset/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ListFolderLongpollError (open union)
resetVoidIndicates that the cursor has been invalidated. Call list_folder to obtain a new cursor.
See also general errors.

/list_revisions


Description

Returns revisions for files based on a file path or a file id. The file path or file id is identified from the latest file entry at the given file path or id. This end point allows your app to query either by file path or file id by setting the mode parameter appropriately. In the ListRevisionsMode.path (default) mode, all revisions at the same file path as the latest file entry are returned. If revisions with the same file id are desired, then mode must be set to ListRevisionsMode.id. The ListRevisionsMode.id mode is useful to retrieve revisions for a given file across moves or renames.

URL Structure
https://api.dropboxapi.com/2/files/list_revisions
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/list_revisions \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"limit\":10,\"mode\":\"path\",\"path\":\"/root/word.docx\"}"
Parameters
{
    "limit": 10,
    "mode": "path",
    "path": "/root/word.docx"
}
ListRevisionsArg
pathString(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)")The path to the file you want to see the revisions of.
modeDetermines the behavior of the API in listing the revisions for a given file path or id. The default for this union is path.
limitUInt64(min=1, max=100)The maximum number of revision entries returned. The default for this field is 10.
before_rev String(min_length=9, pattern="[0-9a-f]+")?If set, ListRevisions will only return revisions prior to before_rev. Can be set using the last revision from a previous call to list_revisions to fetch the next page of revisions. Only supported in path mode. This field is optional.
Returns
{
    "entries": [
        {
            "client_modified": "2015-05-12T15:50:38Z",
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "file_lock_info": {
                "created": "2015-05-12T15:50:38Z",
                "is_lockholder": true,
                "lockholder_name": "Imaginary User"
            },
            "has_explicit_shared_members": false,
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "is_downloadable": true,
            "name": "Prime_Numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "path_lower": "/homework/math/prime_numbers.txt",
            "property_groups": [
                {
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ],
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                }
            ],
            "rev": "a1c10ce0dd78",
            "server_modified": "2015-05-12T15:50:38Z",
            "sharing_info": {
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "parent_shared_folder_id": "84528192421",
                "read_only": true
            },
            "size": 7212
        }
    ],
    "is_deleted": false
}
ListRevisionsResult
is_deletedBooleanIf the file identified by the latest revision in the response is either deleted or moved. If before_rev is set, this refers to the latest revision of the file older than before_rev.
entriesList of ()The revisions for the file. Only revisions that are not deleted will show up here.
server_deleted Timestamp(format="%Y-%m-%dT%H:%M:%SZ")?The time of deletion if the file was deleted. This field is optional.
Errors
Example: invalid_before_rev
{
    "error": {
        ".tag": "invalid_before_rev"
    },
    "error_summary": "invalid_before_rev/..."
}
Example: before_rev_not_supported
{
    "error": {
        ".tag": "before_rev_not_supported"
    },
    "error_summary": "before_rev_not_supported/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ListRevisionsError (open union)
path
invalid_before_revVoidThe revision in before_rev is invalid.
before_rev_not_supportedVoidThe before_rev argument is only supported in path mode.
See also general errors.

/lock_file_batch


Description

Lock the files at the given paths. A locked file will be writable only by the lock holder. A successful response indicates that the file has been locked. Returns a list of the locked file paths and their metadata after this operation.

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

URL Structure
https://api.dropboxapi.com/2/files/lock_file_batch
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/lock_file_batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"entries\":[{\"path\":\"/John Doe/sample/test.pdf\"}]}"
Parameters
{
    "entries": [
        {
            "path": "/John Doe/sample/test.pdf"
        }
    ]
}
LockFileBatchArg
entriesList of ()List of 'entries'. Each 'entry' contains a path of the file which will be locked or queried. Duplicate path arguments in the batch are considered only once.
Returns
{
    "entries": [
        {
            ".tag": "success",
            "lock": {
                "content": {
                    ".tag": "single_user",
                    "created": "2015-05-12T15:50:38Z",
                    "lock_holder_account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "lock_holder_team_id": "dbtid:1234abcd"
                }
            },
            "metadata": {
                ".tag": "file",
                "client_modified": "2015-05-12T15:50:38Z",
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "file_lock_info": {
                    "created": "2015-05-12T15:50:38Z",
                    "is_lockholder": true,
                    "lockholder_name": "Imaginary User"
                },
                "has_explicit_shared_members": false,
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "is_downloadable": true,
                "name": "Prime_Numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "path_lower": "/homework/math/prime_numbers.txt",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "rev": "a1c10ce0dd78",
                "server_modified": "2015-05-12T15:50:38Z",
                "sharing_info": {
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "parent_shared_folder_id": "84528192421",
                    "read_only": true
                },
                "size": 7212
            }
        }
    ]
}
LockFileBatchResult
entriesList of ()Each Entry in the 'entries' will have '.tag' with the operation status (e.g. success), the metadata for the file and the lock state after the operation.
Errors
Example: too_many_write_operations
{
    "error": {
        ".tag": "too_many_write_operations"
    },
    "error_summary": "too_many_write_operations/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: no_write_permission
{
    "error": {
        ".tag": "no_write_permission"
    },
    "error_summary": "no_write_permission/..."
}
Example: cannot_be_locked
{
    "error": {
        ".tag": "cannot_be_locked"
    },
    "error_summary": "cannot_be_locked/..."
}
Example: file_not_shared
{
    "error": {
        ".tag": "file_not_shared"
    },
    "error_summary": "file_not_shared/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
LockFileError (open union)
path_lookupCould not find the specified resource.
too_many_write_operationsVoidThere are too many write operations in user's Dropbox. Please retry this request.
too_many_filesVoidThere are too many files in one request. Please retry with fewer files.
no_write_permissionVoidThe user does not have permissions to change the lock state or access the file.
cannot_be_lockedVoidItem is a type that cannot be locked.
file_not_sharedVoidRequested file is not currently shared.
lock_conflictThe user action conflicts with an existing lock on the file.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/move


Description

Move a file or folder to a different location in the user's Dropbox. If the source path is a folder all its contents will be moved. Note that we do not currently support case-only renaming.

URL Structure
https://api.dropboxapi.com/2/files/move_v2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/move_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"allow_ownership_transfer\":false,\"allow_shared_folder\":false,\"autorename\":false,\"from_path\":\"/Homework/math\",\"to_path\":\"/Homework/algebra\"}"
Parameters
{
    "allow_ownership_transfer": false,
    "allow_shared_folder": false,
    "autorename": false,
    "from_path": "/Homework/math",
    "to_path": "/Homework/algebra"
}
RelocationArg
from_pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)")Path in the user's Dropbox to be copied or moved.
to_pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)")Path in the user's Dropbox that is the destination.
allow_shared_folderdeprecatedBooleanField is deprecated. This flag has no effect. The default for this field is False.
autorenameBooleanIf there's a conflict, have the Dropbox server try to autorename the file to avoid the conflict. The default for this field is False.
allow_ownership_transferBooleanAllow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies. The default for this field is False.
Returns
{
    "metadata": {
        ".tag": "file",
        "client_modified": "2015-05-12T15:50:38Z",
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "file_lock_info": {
            "created": "2015-05-12T15:50:38Z",
            "is_lockholder": true,
            "lockholder_name": "Imaginary User"
        },
        "has_explicit_shared_members": false,
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "is_downloadable": true,
        "name": "Prime_Numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "path_lower": "/homework/math/prime_numbers.txt",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "rev": "a1c10ce0dd78",
        "server_modified": "2015-05-12T15:50:38Z",
        "sharing_info": {
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "parent_shared_folder_id": "84528192421",
            "read_only": true
        },
        "size": 7212
    }
}
RelocationResult
metadataMetadata of the relocated object.
Errors
Example: cant_copy_shared_folder
{
    "error": {
        ".tag": "cant_copy_shared_folder"
    },
    "error_summary": "cant_copy_shared_folder/..."
}
Example: cant_nest_shared_folder
{
    "error": {
        ".tag": "cant_nest_shared_folder"
    },
    "error_summary": "cant_nest_shared_folder/..."
}
Example: cant_move_folder_into_itself
{
    "error": {
        ".tag": "cant_move_folder_into_itself"
    },
    "error_summary": "cant_move_folder_into_itself/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: duplicated_or_nested_paths
{
    "error": {
        ".tag": "duplicated_or_nested_paths"
    },
    "error_summary": "duplicated_or_nested_paths/..."
}
Example: cant_transfer_ownership
{
    "error": {
        ".tag": "cant_transfer_ownership"
    },
    "error_summary": "cant_transfer_ownership/..."
}
Example: insufficient_quota
{
    "error": {
        ".tag": "insufficient_quota"
    },
    "error_summary": "insufficient_quota/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: cant_move_shared_folder
{
    "error": {
        ".tag": "cant_move_shared_folder"
    },
    "error_summary": "cant_move_shared_folder/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
RelocationError (open union)
from_lookup
from_write
to
cant_copy_shared_folderVoidShared folders can't be copied.
cant_nest_shared_folderVoidYour move operation would result in nested shared folders. This is not allowed.
cant_move_folder_into_itselfVoidYou cannot move a folder into itself.
too_many_filesVoidThe operation would involve more than 10,000 files and folders.
duplicated_or_nested_pathsVoidThere are duplicated/nested paths among RelocationArg.from_path and RelocationArg.to_path.
cant_transfer_ownershipVoidYour move operation would result in an ownership transfer. You may reissue the request with the field RelocationArg.allow_ownership_transfer to true.
insufficient_quotaVoidThe current user does not have enough space to move or copy the files.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
cant_move_shared_folderVoidCan't move the shared folder to the given destination.
cant_move_into_vaultSome content cannot be moved into Vault under certain circumstances, see detailed error.
cant_move_into_familySome content cannot be moved into the Family Room folder under certain circumstances, see detailed error.
See also general errors.

/move_batch


Description

Move multiple files or folders to different locations at once in the user's Dropbox. Note that we do not currently support case-only renaming. This route will replace move_batch:1. The main difference is this route will return status for each entry, while move_batch:1 raises failure if any entry fails. This route will either finish synchronously, or return a job ID and do the async move job in background. Please use move_batch/check:2 to check the job status.

URL Structure
https://api.dropboxapi.com/2/files/move_batch_v2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/move_batch_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"allow_ownership_transfer\":false,\"autorename\":false,\"entries\":[{\"from_path\":\"/Homework/math\",\"to_path\":\"/Homework/algebra\"}]}"
Parameters
{
    "allow_ownership_transfer": false,
    "autorename": false,
    "entries": [
        {
            "from_path": "/Homework/math",
            "to_path": "/Homework/algebra"
        }
    ]
}
MoveBatchArg
entriesList of (, min_items=1, max_items=1000)List of entries to be moved or copied. Each entry is RelocationPath.
autorenameBooleanIf there's a conflict with any file, have the Dropbox server try to autorename that file to avoid the conflict. The default for this field is False.
allow_ownership_transferBooleanAllow moves by owner even if it would result in an ownership transfer for the content being moved. This does not apply to copies. The default for this field is False.
Returns
Example: complete
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "success": {
                ".tag": "file",
                "client_modified": "2015-05-12T15:50:38Z",
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "file_lock_info": {
                    "created": "2015-05-12T15:50:38Z",
                    "is_lockholder": true,
                    "lockholder_name": "Imaginary User"
                },
                "has_explicit_shared_members": false,
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "is_downloadable": true,
                "name": "Prime_Numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "path_lower": "/homework/math/prime_numbers.txt",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "rev": "a1c10ce0dd78",
                "server_modified": "2015-05-12T15:50:38Z",
                "sharing_info": {
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "parent_shared_folder_id": "84528192421",
                    "read_only": true
                },
                "size": 7212
            }
        }
    ]
}
Example: async_job_id
{
    ".tag": "async_job_id",
    "async_job_id": "34g93hh34h04y384084"
}
RelocationBatchV2Launch (union)
Result returned by copy_batch:2 or move_batch:2 that may either launch an asynchronous job or complete synchronously.
async_job_idString(min_length=1)This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
complete
Errors
No endpoint-specific errors.
See also general errors.

/move_batch/check


Description

Returns the status of an asynchronous job for move_batch:2. It returns list of results for each entry.

URL Structure
https://api.dropboxapi.com/2/files/move_batch/check_v2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/move_batch/check_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"async_job_id\":\"34g93hh34h04y384084\"}"
Parameters
{
    "async_job_id": "34g93hh34h04y384084"
}
PollArg
Arguments for methods that poll the status of an asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Returns
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "success": {
                ".tag": "file",
                "client_modified": "2015-05-12T15:50:38Z",
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "file_lock_info": {
                    "created": "2015-05-12T15:50:38Z",
                    "is_lockholder": true,
                    "lockholder_name": "Imaginary User"
                },
                "has_explicit_shared_members": false,
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "is_downloadable": true,
                "name": "Prime_Numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "path_lower": "/homework/math/prime_numbers.txt",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "rev": "a1c10ce0dd78",
                "server_modified": "2015-05-12T15:50:38Z",
                "sharing_info": {
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "parent_shared_folder_id": "84528192421",
                    "read_only": true
                },
                "size": 7212
            }
        }
    ]
}
Example: in_progress
{
    ".tag": "in_progress"
}
RelocationBatchV2JobStatus (union)
Result returned by copy_batch/check:2 or move_batch/check:2 that may either be in progress or completed with result for each entry.
in_progressVoidThe asynchronous job is still in progress.
completeThe copy or move batch job has finished.
Errors
Example: invalid_async_job_id
{
    "error": {
        ".tag": "invalid_async_job_id"
    },
    "error_summary": "invalid_async_job_id/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
PollError (open union)
Error returned by methods for polling the status of asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
invalid_async_job_idVoidThe job ID is invalid.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/paper/create


PREVIEW - may change or disappear without notice
Description

Creates a new Paper doc with the provided content.

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

URL Structure
https://api.dropboxapi.com/2/files/paper/create
Authentication
User Authentication
Endpoint format
Content-upload
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/paper/create \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"import_format\":\"html\",\"path\":\"/Paper Docs/New Doc.paper\"}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "import_format": "html",
    "path": "/Paper Docs/New Doc.paper"
}
PaperCreateArg
pathString(pattern="/(.|[\r\n])*")The fully qualified path to the location in the user's Dropbox where the Paper Doc should be created. This should include the document's title and end with .paper.
import_formatThe format of the provided data.
Returns
{
    "file_id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "paper_revision": 1,
    "result_path": "/Paper Docs/New Doc.paper",
    "url": "https://www.dropbox.com/scl/xxx.paper?dl=0"
}
PaperCreateResult
urlStringURL to open the Paper Doc.
result_pathStringThe fully qualified path the Paper Doc was actually created at.
file_idString(min_length=4, pattern="id:.+")The id to use in Dropbox APIs when referencing the Paper Doc.
paper_revisionInt64The current doc revision.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: content_malformed
{
    "error": {
        ".tag": "content_malformed"
    },
    "error_summary": "content_malformed/..."
}
Example: doc_length_exceeded
{
    "error": {
        ".tag": "doc_length_exceeded"
    },
    "error_summary": "doc_length_exceeded/..."
}
Example: image_size_exceeded
{
    "error": {
        ".tag": "image_size_exceeded"
    },
    "error_summary": "image_size_exceeded/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: invalid_path
{
    "error": {
        ".tag": "invalid_path"
    },
    "error_summary": "invalid_path/..."
}
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: invalid_file_extension
{
    "error": {
        ".tag": "invalid_file_extension"
    },
    "error_summary": "invalid_file_extension/..."
}
Example: paper_disabled
{
    "error": {
        ".tag": "paper_disabled"
    },
    "error_summary": "paper_disabled/..."
}
PaperCreateError (union)
insufficient_permissionsVoidYour account does not have permissions to edit Paper docs.
content_malformedVoidThe provided content was malformed and cannot be imported to Paper.
doc_length_exceededVoidThe Paper doc would be too large, split the content into multiple docs.
image_size_exceededVoidThe imported document contains an image that is too large. The current limit is 1MB. This only applies to HTML with data URI.
invalid_pathVoidThe file could not be saved to the specified location.
email_unverifiedVoidThe user's email must be verified to create Paper docs.
invalid_file_extensionVoidThe file path must end in .paper.
paper_disabledVoidPaper is disabled for your team.
See also general errors.

/paper/update


PREVIEW - may change or disappear without notice
Description

Updates an existing Paper doc with the provided content.

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

URL Structure
https://api.dropboxapi.com/2/files/paper/update
Authentication
User Authentication
Endpoint format
Content-upload
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/paper/update \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"doc_update_policy\":\"update\",\"import_format\":\"html\",\"paper_revision\":123,\"path\":\"/Paper Docs/My Doc.paper\"}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "doc_update_policy": "update",
    "import_format": "html",
    "paper_revision": 123,
    "path": "/Paper Docs/My Doc.paper"
}
PaperUpdateArg
pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)")Path in the user's Dropbox to update. The path must correspond to a Paper doc or an error will be returned.
import_formatThe format of the provided data.
doc_update_policyHow the provided content should be applied to the doc.
paper_revision Int64?The latest doc revision. Required when doc_update_policy is update. This value must match the current revision of the doc or error revision_mismatch will be returned. This field is optional.
Returns
{
    "paper_revision": 124
}
PaperUpdateResult
paper_revisionInt64The current doc revision.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: content_malformed
{
    "error": {
        ".tag": "content_malformed"
    },
    "error_summary": "content_malformed/..."
}
Example: doc_length_exceeded
{
    "error": {
        ".tag": "doc_length_exceeded"
    },
    "error_summary": "doc_length_exceeded/..."
}
Example: image_size_exceeded
{
    "error": {
        ".tag": "image_size_exceeded"
    },
    "error_summary": "image_size_exceeded/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: revision_mismatch
{
    "error": {
        ".tag": "revision_mismatch"
    },
    "error_summary": "revision_mismatch/..."
}
Example: doc_archived
{
    "error": {
        ".tag": "doc_archived"
    },
    "error_summary": "doc_archived/..."
}
Example: doc_deleted
{
    "error": {
        ".tag": "doc_deleted"
    },
    "error_summary": "doc_deleted/..."
}
PaperUpdateError (union)
insufficient_permissionsVoidYour account does not have permissions to edit Paper docs.
content_malformedVoidThe provided content was malformed and cannot be imported to Paper.
doc_length_exceededVoidThe Paper doc would be too large, split the content into multiple docs.
image_size_exceededVoidThe imported document contains an image that is too large. The current limit is 1MB. This only applies to HTML with data URI.
path
revision_mismatchVoidThe provided revision does not match the document head.
doc_archivedVoidThis operation is not allowed on archived Paper docs.
doc_deletedVoidThis operation is not allowed on deleted Paper docs.
See also general errors.

/permanently_delete


Description

Permanently delete the file or folder at a given path (see https://www.dropbox.com/en/help/40). If the given file or folder is not yet deleted, this route will first delete it. It is possible for this route to successfully delete, then fail to permanently delete. Note: This endpoint is only available for Dropbox Business apps.

URL Structure
https://api.dropboxapi.com/2/files/permanently_delete
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.permanent_delete
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/permanently_delete \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/Homework/math/Prime_Numbers.txt\"}"
Parameters
{
    "path": "/Homework/math/Prime_Numbers.txt"
}
DeleteArg
pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)")Path in the user's Dropbox to delete.
parent_rev String(min_length=9, pattern="[0-9a-f]+")?Perform delete if given "rev" matches the existing file's latest "rev". This field does not support deleting a folder. This field is optional.
Returns
No return values.
Errors
Example: too_many_write_operations
{
    "error": {
        ".tag": "too_many_write_operations"
    },
    "error_summary": "too_many_write_operations/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
DeleteError (open union)
path_lookup
path_write
too_many_write_operationsVoidThere are too many write operations in user's Dropbox. Please retry this request.
too_many_filesVoidThere are too many files in one request. Please retry with fewer files.
See also general errors.

/restore


Description

Restore a specific revision of a file to the given path.

URL Structure
https://api.dropboxapi.com/2/files/restore
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/restore \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/root/word.docx\",\"rev\":\"a1c10ce0dd78\"}"
Parameters
{
    "path": "/root/word.docx",
    "rev": "a1c10ce0dd78"
}
RestoreArg
pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)")The path to save the restored file.
revString(min_length=9, pattern="[0-9a-f]+")The revision to restore.
Returns
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "file_lock_info": {
        "created": "2015-05-12T15:50:38Z",
        "is_lockholder": true,
        "lockholder_name": "Imaginary User"
    },
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
Example: search_file_metadata
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
FileMetadata
nameStringThe last component of the path (including extension). This never contains a slash.
idString(min_length=1)A unique identifier for the file.
client_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")For files, this is the modification time set by the desktop client when the file was added to Dropbox. Since this time is not verified (the Dropbox server stores whatever the desktop client sends up), this should only be used for display purposes (such as sorting) and not, for example, to determine if a file has changed or not.
server_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")The last time the file was modified on Dropbox.
revString(min_length=9, pattern="[0-9a-f]+")A unique identifier for the current revision of a file. This field is the same rev as elsewhere in the API and can be used to detect changes and avoid conflicts.
sizeUInt64The file size in bytes.
path_lower String?The lowercased full path in the user's Dropbox. This always starts with a slash. This field will be null if the file or folder is not mounted. This field is optional.
path_display String?The cased path to be used for display purposes only. In rare instances the casing will not correctly match the user's filesystem, but this behavior will match the path provided in the Core API v1, and at least the last path component will have the correct casing. Changes to only the casing of paths won't be returned by list_folder/continue. This field will be null if the file or folder is not mounted. This field is optional.
parent_shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")?Field is deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
preview_url String?The preview URL of the file. This field is optional.
media_info?Additional information if the file is a photo or video. This field will not be set on entries returned by list_folder, list_folder/continue, or get_thumbnail_batch, starting December 2, 2019. This field is optional.
symlink_info?Set if this file is a symlink. This field is optional.
sharing_info?Set if this file is contained in a shared folder. This field is optional.
is_downloadableBooleanIf true, file can be downloaded directly; else the file must be exported. The default for this field is True.
export_info?Information about format this file can be exported to. This filed must be set if is_downloadable is set to false. This field is optional.
property_groupsList of ()?Additional information if the file has custom properties with the property template specified. This field is optional.
has_explicit_shared_members Boolean?This flag will only be present if include_has_explicit_shared_members is true in list_folder or get_metadata. If this flag is present, it will be true if this file has any explicit shared members. This is different from sharing_info in that this could be true in the case where a file has explicit members but is not contained within a shared folder. This field is optional.
content_hash String(min_length=64, max_length=64)?A hash of the file content. This field can be used to verify data integrity. For more information see our Content hash page. This field is optional.
file_lock_info?If present, the metadata associated with the file's current lock. This field is optional.
Errors
Example: invalid_revision
{
    "error": {
        ".tag": "invalid_revision"
    },
    "error_summary": "invalid_revision/..."
}
Example: in_progress
{
    "error": {
        ".tag": "in_progress"
    },
    "error_summary": "in_progress/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
RestoreError (open union)
path_lookupAn error occurs when downloading metadata for the file.
path_writeAn error occurs when trying to restore the file to that path.
invalid_revisionVoidThe revision is invalid. It may not exist or may point to a deleted file.
in_progressVoidThe restore is currently executing, but has not yet completed.
See also general errors.

/save_url


Description

Save the data from a specified URL into a file in user's Dropbox. Note that the transfer from the URL must complete within 15 minutes, or the operation will time out and the job will fail. If the given path already exists, the file will be renamed to avoid the conflict (e.g. myfile (1).txt).

URL Structure
https://api.dropboxapi.com/2/files/save_url
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/save_url \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/a.txt\",\"url\":\"http://example.com/a.txt\"}"
Parameters
{
    "path": "/a.txt",
    "url": "http://example.com/a.txt"
}
SaveUrlArg
pathString(pattern="/(.|[\r\n])*")The path in Dropbox where the URL will be saved to.
urlStringThe URL to be saved.
Returns
{
    ".tag": "complete",
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "file_lock_info": {
        "created": "2015-05-12T15:50:38Z",
        "is_lockholder": true,
        "lockholder_name": "Imaginary User"
    },
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
SaveUrlResult (union)
async_job_idString(min_length=1)This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
completeMetadata of the file where the URL is saved to.
Errors
Example: download_failed
{
    "error": {
        ".tag": "download_failed"
    },
    "error_summary": "download_failed/..."
}
Example: invalid_url
{
    "error": {
        ".tag": "invalid_url"
    },
    "error_summary": "invalid_url/..."
}
Example: not_found
{
    "error": {
        ".tag": "not_found"
    },
    "error_summary": "not_found/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SaveUrlError (open union)
path
download_failedVoidFailed downloading the given URL. The URL may be password-protected and the password provided was incorrect, or the link may be disabled.
invalid_urlVoidThe given URL is invalid.
not_foundVoidThe file where the URL is saved to no longer exists.
See also general errors.

/save_url/check_job_status


Description

Check the status of a save_url job.

URL Structure
https://api.dropboxapi.com/2/files/save_url/check_job_status
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/save_url/check_job_status \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"async_job_id\":\"34g93hh34h04y384084\"}"
Parameters
{
    "async_job_id": "34g93hh34h04y384084"
}
PollArg
Arguments for methods that poll the status of an asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Returns
{
    ".tag": "in_progress"
}
SaveUrlJobStatus (union)
in_progressVoidThe asynchronous job is still in progress.
completeMetadata of the file where the URL is saved to.
failed
Errors
Example: invalid_async_job_id
{
    "error": {
        ".tag": "invalid_async_job_id"
    },
    "error_summary": "invalid_async_job_id/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
PollError (open union)
Error returned by methods for polling the status of asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
invalid_async_job_idVoidThe job ID is invalid.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/search


Description

Searches for files and folders. Note: search:2 along with search/continue:2 can only be used to retrieve a maximum of 10,000 matches. Recent changes may not immediately be reflected in search results due to a short delay in indexing. Duplicate results may be returned across pages. Some results may not be returned.

URL Structure
https://api.dropboxapi.com/2/files/search_v2
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/search_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"match_field_options\":{\"include_highlights\":false},\"options\":{\"file_status\":\"active\",\"filename_only\":false,\"max_results\":20,\"path\":\"/Folder\"},\"query\":\"cat\"}"
Parameters
{
    "match_field_options": {
        "include_highlights": false
    },
    "options": {
        "file_status": "active",
        "filename_only": false,
        "max_results": 20,
        "path": "/Folder"
    },
    "query": "cat"
}
SearchV2Arg
queryString(max_length=1000)The string to search for. May match across multiple fields based on the request arguments.
options?Options for more targeted search results. This field is optional.
match_field_options?Options for search results match fields. This field is optional.
include_highlightsdeprecated Boolean?Field is deprecated. Deprecated and moved this option to SearchMatchFieldOptions. This field is optional.
Returns
{
    "has_more": false,
    "matches": [
        {
            "metadata": {
                ".tag": "metadata",
                "metadata": {
                    ".tag": "file",
                    "client_modified": "2015-05-12T15:50:38Z",
                    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                    "has_explicit_shared_members": false,
                    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                    "is_downloadable": true,
                    "name": "Prime_Numbers.txt",
                    "path_display": "/Homework/math/Prime_Numbers.txt",
                    "path_lower": "/homework/math/prime_numbers.txt",
                    "rev": "a1c10ce0dd78",
                    "server_modified": "2015-05-12T15:50:38Z",
                    "sharing_info": {
                        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                        "parent_shared_folder_id": "84528192421",
                        "read_only": true
                    },
                    "size": 7212
                }
            }
        }
    ]
}
SearchV2Result
matchesList of ()A list (possibly empty) of matches for the query.
has_moreBooleanUsed for paging. If true, indicates there is another page of results available that can be fetched by calling search/continue:2 with the cursor.
cursor String(min_length=1)?Pass the cursor into search/continue:2 to fetch the next page of results. This field is optional.
Errors
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SearchError (open union)
path
invalid_argument String? This field is optional.
internal_errorVoidSomething went wrong, please try again.
See also general errors.

/search/continue


Description

Fetches the next page of search results returned from search:2. Note: search:2 along with search/continue:2 can only be used to retrieve a maximum of 10,000 matches. Recent changes may not immediately be reflected in search results due to a short delay in indexing. Duplicate results may be returned across pages. Some results may not be returned.

URL Structure
https://api.dropboxapi.com/2/files/search/continue_v2
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/search/continue_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
SearchV2ContinueArg
cursorString(min_length=1)The cursor returned by your last call to search:2. Used to fetch the next page of results.
Returns
{
    "has_more": false,
    "matches": [
        {
            "metadata": {
                ".tag": "metadata",
                "metadata": {
                    ".tag": "file",
                    "client_modified": "2015-05-12T15:50:38Z",
                    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                    "has_explicit_shared_members": false,
                    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                    "is_downloadable": true,
                    "name": "Prime_Numbers.txt",
                    "path_display": "/Homework/math/Prime_Numbers.txt",
                    "path_lower": "/homework/math/prime_numbers.txt",
                    "rev": "a1c10ce0dd78",
                    "server_modified": "2015-05-12T15:50:38Z",
                    "sharing_info": {
                        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                        "parent_shared_folder_id": "84528192421",
                        "read_only": true
                    },
                    "size": 7212
                }
            }
        }
    ]
}
SearchV2Result
matchesList of ()A list (possibly empty) of matches for the query.
has_moreBooleanUsed for paging. If true, indicates there is another page of results available that can be fetched by calling search/continue:2 with the cursor.
cursor String(min_length=1)?Pass the cursor into search/continue:2 to fetch the next page of results. This field is optional.
Errors
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SearchError (open union)
path
invalid_argument String? This field is optional.
internal_errorVoidSomething went wrong, please try again.
See also general errors.

/tags/add


PREVIEW - may change or disappear without notice
Description

Add a tag to an item. A tag is a string. The strings are automatically converted to lowercase letters. No more than 20 tags can be added to a given item.

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

URL Structure
https://api.dropboxapi.com/2/files/tags/add
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/tags/add \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/Prime_Numbers.txt\",\"tag_text\":\"my_tag\"}"
Parameters
{
    "path": "/Prime_Numbers.txt",
    "tag_text": "my_tag"
}
AddTagArg
pathString(pattern="/(.|[\r\n])*")Path to the item to be tagged.
tag_textString(min_length=1, max_length=32, pattern="[\w]+")The value of the tag to add. Will be automatically converted to lowercase letters.
Returns
No return values.
Errors
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: too_many_tags
{
    "error": {
        ".tag": "too_many_tags"
    },
    "error_summary": "too_many_tags/..."
}
AddTagError (union)
path
too_many_tagsVoidThe item already has the maximum supported number of tags.
See also general errors.

/tags/get


PREVIEW - may change or disappear without notice
Description

Get list of tags assigned to items.

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

URL Structure
https://api.dropboxapi.com/2/files/tags/get
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/tags/get \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"paths\":[\"/Prime_Numbers.txt\"]}"
Parameters
{
    "paths": [
        "/Prime_Numbers.txt"
    ]
}
GetTagsArg
paths List of (String(pattern="/(.|[\r\n])*"))Path to the items.
Returns
{
    "paths_to_tags": [
        {
            "path": "/Prime_Numbers.txt",
            "tags": [
                {
                    ".tag": "user_generated_tag",
                    "tag_text": "my_tag"
                }
            ]
        }
    ]
}
GetTagsResult
paths_to_tagsList of ()List of paths and their corresponding tags.
Errors
BaseTagError (open union)
path
See also general errors.

/tags/remove


PREVIEW - may change or disappear without notice
Description

Remove a tag from an item.

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

URL Structure
https://api.dropboxapi.com/2/files/tags/remove
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/tags/remove \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/Prime_Numbers.txt\",\"tag_text\":\"my_tag\"}"
Parameters
{
    "path": "/Prime_Numbers.txt",
    "tag_text": "my_tag"
}
RemoveTagArg
pathString(pattern="/(.|[\r\n])*")Path to the item to tag.
tag_textString(min_length=1, max_length=32, pattern="[\w]+")The tag to remove. Will be automatically converted to lowercase letters.
Returns
No return values.
Errors
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: tag_not_present
{
    "error": {
        ".tag": "tag_not_present"
    },
    "error_summary": "tag_not_present/..."
}
RemoveTagError (union)
path
tag_not_presentVoidThat tag doesn't exist at this path.
See also general errors.

/unlock_file_batch


Description

Unlock the files at the given paths. A locked file can only be unlocked by the lock holder or, if a business account, a team admin. A successful response indicates that the file has been unlocked. Returns a list of the unlocked file paths and their metadata after this operation.

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

URL Structure
https://api.dropboxapi.com/2/files/unlock_file_batch
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/unlock_file_batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"entries\":[{\"path\":\"/John Doe/sample/test.pdf\"}]}"
Parameters
{
    "entries": [
        {
            "path": "/John Doe/sample/test.pdf"
        }
    ]
}
UnlockFileBatchArg
entriesList of ()List of 'entries'. Each 'entry' contains a path of the file which will be unlocked. Duplicate path arguments in the batch are considered only once.
Returns
{
    "entries": [
        {
            ".tag": "success",
            "lock": {
                "content": {
                    ".tag": "single_user",
                    "created": "2015-05-12T15:50:38Z",
                    "lock_holder_account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "lock_holder_team_id": "dbtid:1234abcd"
                }
            },
            "metadata": {
                ".tag": "file",
                "client_modified": "2015-05-12T15:50:38Z",
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
                "file_lock_info": {
                    "created": "2015-05-12T15:50:38Z",
                    "is_lockholder": true,
                    "lockholder_name": "Imaginary User"
                },
                "has_explicit_shared_members": false,
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "is_downloadable": true,
                "name": "Prime_Numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "path_lower": "/homework/math/prime_numbers.txt",
                "property_groups": [
                    {
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ],
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                    }
                ],
                "rev": "a1c10ce0dd78",
                "server_modified": "2015-05-12T15:50:38Z",
                "sharing_info": {
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                    "parent_shared_folder_id": "84528192421",
                    "read_only": true
                },
                "size": 7212
            }
        }
    ]
}
LockFileBatchResult
entriesList of ()Each Entry in the 'entries' will have '.tag' with the operation status (e.g. success), the metadata for the file and the lock state after the operation.
Errors
Example: too_many_write_operations
{
    "error": {
        ".tag": "too_many_write_operations"
    },
    "error_summary": "too_many_write_operations/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: no_write_permission
{
    "error": {
        ".tag": "no_write_permission"
    },
    "error_summary": "no_write_permission/..."
}
Example: cannot_be_locked
{
    "error": {
        ".tag": "cannot_be_locked"
    },
    "error_summary": "cannot_be_locked/..."
}
Example: file_not_shared
{
    "error": {
        ".tag": "file_not_shared"
    },
    "error_summary": "file_not_shared/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
LockFileError (open union)
path_lookupCould not find the specified resource.
too_many_write_operationsVoidThere are too many write operations in user's Dropbox. Please retry this request.
too_many_filesVoidThere are too many files in one request. Please retry with fewer files.
no_write_permissionVoidThe user does not have permissions to change the lock state or access the file.
cannot_be_lockedVoidItem is a type that cannot be locked.
file_not_sharedVoidRequested file is not currently shared.
lock_conflictThe user action conflicts with an existing lock on the file.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/upload


Description

Create a new file with the contents provided in the request. Do not use this to upload a file larger than 150 MiB. Instead, create an upload session with upload_session/start. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

URL Structure
https://content.dropboxapi.com/2/files/upload
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
Content-upload
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/upload \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"autorename\":false,\"mode\":\"add\",\"mute\":false,\"path\":\"/Homework/math/Matrices.txt\",\"strict_conflict\":false}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "autorename": false,
    "mode": "add",
    "mute": false,
    "path": "/Homework/math/Matrices.txt",
    "strict_conflict": false
}
UploadArg
pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)")Path in the user's Dropbox to save the file.
modeSelects what to do if the file already exists. The default for this union is add.
autorenameBooleanIf there's a conflict, as determined by mode, have the Dropbox server try to autorename the file to avoid conflict. The default for this field is False.
client_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ")?The value to store as the client_modified timestamp. Dropbox automatically records the time at which the file was written to the Dropbox servers. It can also record an additional timestamp, provided by Dropbox desktop clients, mobile clients, and API apps of when the file was actually created or modified. This field is optional.
muteBooleanNormally, users are made aware of any file modifications in their Dropbox account via notifications in the client software. If true, this tells the clients that this modification shouldn't result in a user notification. The default for this field is False.
property_groupsList of ()?List of custom properties to add to file. This field is optional.
strict_conflictBooleanBe more strict about how each WriteMode detects conflict. For example, always return a conflict error when mode = WriteMode.update and the given "rev" doesn't match the existing file's "rev", even if the existing file has been deleted. This also forces a conflict even when the target path refers to a file with identical contents. The default for this field is False.
content_hash String(min_length=64, max_length=64)?A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page. This field is optional.
Returns
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "file_lock_info": {
        "created": "2015-05-12T15:50:38Z",
        "is_lockholder": true,
        "lockholder_name": "Imaginary User"
    },
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
Example: search_file_metadata
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
FileMetadata
nameStringThe last component of the path (including extension). This never contains a slash.
idString(min_length=1)A unique identifier for the file.
client_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")For files, this is the modification time set by the desktop client when the file was added to Dropbox. Since this time is not verified (the Dropbox server stores whatever the desktop client sends up), this should only be used for display purposes (such as sorting) and not, for example, to determine if a file has changed or not.
server_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")The last time the file was modified on Dropbox.
revString(min_length=9, pattern="[0-9a-f]+")A unique identifier for the current revision of a file. This field is the same rev as elsewhere in the API and can be used to detect changes and avoid conflicts.
sizeUInt64The file size in bytes.
path_lower String?The lowercased full path in the user's Dropbox. This always starts with a slash. This field will be null if the file or folder is not mounted. This field is optional.
path_display String?The cased path to be used for display purposes only. In rare instances the casing will not correctly match the user's filesystem, but this behavior will match the path provided in the Core API v1, and at least the last path component will have the correct casing. Changes to only the casing of paths won't be returned by list_folder/continue. This field will be null if the file or folder is not mounted. This field is optional.
parent_shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")?Field is deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
preview_url String?The preview URL of the file. This field is optional.
media_info?Additional information if the file is a photo or video. This field will not be set on entries returned by list_folder, list_folder/continue, or get_thumbnail_batch, starting December 2, 2019. This field is optional.
symlink_info?Set if this file is a symlink. This field is optional.
sharing_info?Set if this file is contained in a shared folder. This field is optional.
is_downloadableBooleanIf true, file can be downloaded directly; else the file must be exported. The default for this field is True.
export_info?Information about format this file can be exported to. This filed must be set if is_downloadable is set to false. This field is optional.
property_groupsList of ()?Additional information if the file has custom properties with the property template specified. This field is optional.
has_explicit_shared_members Boolean?This flag will only be present if include_has_explicit_shared_members is true in list_folder or get_metadata. If this flag is present, it will be true if this file has any explicit shared members. This is different from sharing_info in that this could be true in the case where a file has explicit members but is not contained within a shared folder. This field is optional.
content_hash String(min_length=64, max_length=64)?A hash of the file content. This field can be used to verify data integrity. For more information see our Content hash page. This field is optional.
file_lock_info?If present, the metadata associated with the file's current lock. This field is optional.
Errors
Example: payload_too_large
{
    "error": {
        ".tag": "payload_too_large"
    },
    "error_summary": "payload_too_large/..."
}
Example: content_hash_mismatch
{
    "error": {
        ".tag": "content_hash_mismatch"
    },
    "error_summary": "content_hash_mismatch/..."
}
Example: encryption_not_supported
{
    "error": {
        ".tag": "encryption_not_supported"
    },
    "error_summary": "encryption_not_supported/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UploadError (open union)
pathUnable to save the uploaded contents to a file.
properties_errorThe supplied property group is invalid. The file has uploaded without property groups.
payload_too_largeVoidThe request payload must be at most 150 MiB.
content_hash_mismatchVoidThe content received by the Dropbox server in this call does not match the provided content hash.
encryption_not_supportedVoidThe file is required to be encrypted, which is not supported in our public API.
See also general errors.

/upload_session/append


Description

Append more data to an upload session. When the parameter close is set, this call will close the session. A single request should not upload more than 150 MiB. The maximum size of a file one can upload to an upload session is 350 GiB. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

URL Structure
https://content.dropboxapi.com/2/files/upload_session/append_v2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
Content-upload
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/upload_session/append_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"close\":false,\"cursor\":{\"offset\":0,\"session_id\":\"1234faaf0678bcde\"}}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "close": false,
    "cursor": {
        "offset": 0,
        "session_id": "1234faaf0678bcde"
    }
}
UploadSessionAppendArg
cursorContains the upload session ID and the offset.
closeBooleanIf true, the current session will be closed, at which point you won't be able to call upload_session/append:2 anymore with the current session. The default for this field is False.
content_hash String(min_length=64, max_length=64)?A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page. This field is optional.
Returns
No return values.
Errors
Example: not_found
{
    "error": {
        ".tag": "not_found"
    },
    "error_summary": "not_found/..."
}
Example: closed
{
    "error": {
        ".tag": "closed"
    },
    "error_summary": "closed/..."
}
Example: too_large
{
    "error": {
        ".tag": "too_large"
    },
    "error_summary": "too_large/..."
}
Example: concurrent_session_invalid_offset
{
    "error": {
        ".tag": "concurrent_session_invalid_offset"
    },
    "error_summary": "concurrent_session_invalid_offset/..."
}
Example: concurrent_session_invalid_data_size
{
    "error": {
        ".tag": "concurrent_session_invalid_data_size"
    },
    "error_summary": "concurrent_session_invalid_data_size/..."
}
Example: payload_too_large
{
    "error": {
        ".tag": "payload_too_large"
    },
    "error_summary": "payload_too_large/..."
}
Example: content_hash_mismatch
{
    "error": {
        ".tag": "content_hash_mismatch"
    },
    "error_summary": "content_hash_mismatch/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UploadSessionAppendError (open union)
not_foundVoidThe upload session ID was not found or has expired. Upload sessions are valid for 7 days.
incorrect_offsetThe specified offset was incorrect. See the value for the correct offset. This error may occur when a previous request was received and processed successfully but the client did not receive the response, e.g. due to a network error.
closedVoidYou are attempting to append data to an upload session that has already been closed (i.e. committed).
too_largeVoidYou can not append to the upload session because the size of a file should not reach the max file size limit (i.e. 350GiB).
concurrent_session_invalid_offsetVoidFor concurrent upload sessions, offset needs to be multiple of 4194304 bytes.
concurrent_session_invalid_data_sizeVoidFor concurrent upload sessions, only chunks with size multiple of 4194304 bytes can be uploaded.
payload_too_largeVoidThe request payload must be at most 150 MiB.
content_hash_mismatchVoidThe content received by the Dropbox server in this call does not match the provided content hash.
See also general errors.

/upload_session/append_batch


Description

Append more data to multiple upload sessions. Each piece of file content to append to each upload session should be concatenated in the request body, in the order delineated by UploadSessionAppendBatchArg.entries and their individual lengths indicated by UploadSessionAppendBatchArgEntry.length. A single request should not upload more than 150 MiB. The maximum size of a file one can upload to an upload session is 350 GiB. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

URL Structure
https://content.dropboxapi.com/2/files/upload_session/append_batch
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
Content-upload
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/upload_session/append_batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"entries\":[{\"close\":false,\"cursor\":{\"offset\":0,\"session_id\":\"1234faaf0678bcde\"},\"length\":12345}]}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "entries": [
        {
            "close": false,
            "cursor": {
                "offset": 0,
                "session_id": "1234faaf0678bcde"
            },
            "length": 12345
        }
    ]
}
Example: multiple
{
    "entries": [
        {
            "close": false,
            "cursor": {
                "offset": 0,
                "session_id": "1234faaf0678bcde"
            },
            "length": 12345
        },
        {
            "close": false,
            "cursor": {
                "offset": 1073741824,
                "session_id": "8dd9d57374911153"
            },
            "length": 67890
        }
    ]
}
UploadSessionAppendBatchArg
entriesList of (, max_items=1000)Append information for each file in the batch.
content_hash String(min_length=64, max_length=64)?A hash of the entire request body which is all the concatenated pieces of file content that were uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page. This field is optional.
Returns
{
    "entries": [
        {
            ".tag": "success"
        }
    ]
}
UploadSessionAppendBatchResult
entriesList of ()Each entry in UploadSessionAppendBatchArg.entries will appear at the same position inside UploadSessionAppendBatchResult.entries.
Errors
Example: payload_too_large
{
    "error": {
        ".tag": "payload_too_large"
    },
    "error_summary": "payload_too_large/..."
}
Example: content_hash_mismatch
{
    "error": {
        ".tag": "content_hash_mismatch"
    },
    "error_summary": "content_hash_mismatch/..."
}
Example: length_mismatch
{
    "error": {
        ".tag": "length_mismatch"
    },
    "error_summary": "length_mismatch/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UploadSessionAppendBatchError (open union)
payload_too_largeVoidThe request payload must be at most 150 MiB.
content_hash_mismatchVoidThe content received by the Dropbox server in this call does not match the provided content hash.
length_mismatchVoidThe total length of the content received by the Dropbox server in this call does not match the total of the provided lengths in the batch arguments.
See also general errors.

/upload_session/finish


Description

Finish an upload session and save the uploaded data to the given file path. A single request should not upload more than 150 MiB. The maximum size of a file one can upload to an upload session is 350 GiB. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

URL Structure
https://content.dropboxapi.com/2/files/upload_session/finish
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
Content-upload
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/upload_session/finish \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"commit\":{\"autorename\":true,\"mode\":\"add\",\"mute\":false,\"path\":\"/Homework/math/Matrices.txt\",\"strict_conflict\":false},\"cursor\":{\"offset\":0,\"session_id\":\"1234faaf0678bcde\"}}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "commit": {
        "autorename": true,
        "mode": "add",
        "mute": false,
        "path": "/Homework/math/Matrices.txt",
        "strict_conflict": false
    },
    "cursor": {
        "offset": 0,
        "session_id": "1234faaf0678bcde"
    }
}
Example: another
{
    "commit": {
        "autorename": true,
        "mode": "add",
        "mute": false,
        "path": "/Homework/math/Vectors.txt",
        "strict_conflict": false
    },
    "cursor": {
        "offset": 1073741824,
        "session_id": "8dd9d57374911153"
    }
}
Example: update
{
    "commit": {
        "autorename": false,
        "mode": {
            ".tag": "update",
            "update": "a1c10ce0dd78"
        },
        "mute": false,
        "path": "/Homework/math/Matrices.txt",
        "property_groups": [
            {
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ],
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
            }
        ],
        "strict_conflict": false
    },
    "cursor": {
        "offset": 0,
        "session_id": "1234faaf0678bcde"
    }
}
UploadSessionFinishArg
cursorContains the upload session ID and the offset.
commitContains the path and other optional modifiers for the commit.
content_hash String(min_length=64, max_length=64)?A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page. This field is optional.
Returns
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "file_lock_info": {
        "created": "2015-05-12T15:50:38Z",
        "is_lockholder": true,
        "lockholder_name": "Imaginary User"
    },
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
Example: search_file_metadata
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
FileMetadata
nameStringThe last component of the path (including extension). This never contains a slash.
idString(min_length=1)A unique identifier for the file.
client_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")For files, this is the modification time set by the desktop client when the file was added to Dropbox. Since this time is not verified (the Dropbox server stores whatever the desktop client sends up), this should only be used for display purposes (such as sorting) and not, for example, to determine if a file has changed or not.
server_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")The last time the file was modified on Dropbox.
revString(min_length=9, pattern="[0-9a-f]+")A unique identifier for the current revision of a file. This field is the same rev as elsewhere in the API and can be used to detect changes and avoid conflicts.
sizeUInt64The file size in bytes.
path_lower String?The lowercased full path in the user's Dropbox. This always starts with a slash. This field will be null if the file or folder is not mounted. This field is optional.
path_display String?The cased path to be used for display purposes only. In rare instances the casing will not correctly match the user's filesystem, but this behavior will match the path provided in the Core API v1, and at least the last path component will have the correct casing. Changes to only the casing of paths won't be returned by list_folder/continue. This field will be null if the file or folder is not mounted. This field is optional.
parent_shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")?Field is deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
preview_url String?The preview URL of the file. This field is optional.
media_info?Additional information if the file is a photo or video. This field will not be set on entries returned by list_folder, list_folder/continue, or get_thumbnail_batch, starting December 2, 2019. This field is optional.
symlink_info?Set if this file is a symlink. This field is optional.
sharing_info?Set if this file is contained in a shared folder. This field is optional.
is_downloadableBooleanIf true, file can be downloaded directly; else the file must be exported. The default for this field is True.
export_info?Information about format this file can be exported to. This filed must be set if is_downloadable is set to false. This field is optional.
property_groupsList of ()?Additional information if the file has custom properties with the property template specified. This field is optional.
has_explicit_shared_members Boolean?This flag will only be present if include_has_explicit_shared_members is true in list_folder or get_metadata. If this flag is present, it will be true if this file has any explicit shared members. This is different from sharing_info in that this could be true in the case where a file has explicit members but is not contained within a shared folder. This field is optional.
content_hash String(min_length=64, max_length=64)?A hash of the file content. This field can be used to verify data integrity. For more information see our Content hash page. This field is optional.
file_lock_info?If present, the metadata associated with the file's current lock. This field is optional.
Errors
Example: too_many_shared_folder_targets
{
    "error": {
        ".tag": "too_many_shared_folder_targets"
    },
    "error_summary": "too_many_shared_folder_targets/..."
}
Example: too_many_write_operations
{
    "error": {
        ".tag": "too_many_write_operations"
    },
    "error_summary": "too_many_write_operations/..."
}
Example: concurrent_session_data_not_allowed
{
    "error": {
        ".tag": "concurrent_session_data_not_allowed"
    },
    "error_summary": "concurrent_session_data_not_allowed/..."
}
Example: concurrent_session_not_closed
{
    "error": {
        ".tag": "concurrent_session_not_closed"
    },
    "error_summary": "concurrent_session_not_closed/..."
}
Example: concurrent_session_missing_data
{
    "error": {
        ".tag": "concurrent_session_missing_data"
    },
    "error_summary": "concurrent_session_missing_data/..."
}
Example: payload_too_large
{
    "error": {
        ".tag": "payload_too_large"
    },
    "error_summary": "payload_too_large/..."
}
Example: content_hash_mismatch
{
    "error": {
        ".tag": "content_hash_mismatch"
    },
    "error_summary": "content_hash_mismatch/..."
}
Example: encryption_not_supported
{
    "error": {
        ".tag": "encryption_not_supported"
    },
    "error_summary": "encryption_not_supported/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UploadSessionFinishError (open union)
lookup_failedThe session arguments are incorrect; the value explains the reason.
pathUnable to save the uploaded contents to a file. Data has already been appended to the upload session. Please retry with empty data body and updated offset.
properties_errorThe supplied property group is invalid. The file has uploaded without property groups.
too_many_shared_folder_targetsdeprecatedVoidField is deprecated. The batch request commits files into too many different shared folders. Please limit your batch request to files contained in a single shared folder.
too_many_write_operationsVoidThere are too many write operations happening in the user's Dropbox. You should retry uploading this file.
concurrent_session_data_not_allowedVoidUploading data not allowed when finishing concurrent upload session.
concurrent_session_not_closedVoidConcurrent upload sessions need to be closed before finishing.
concurrent_session_missing_dataVoidNot all pieces of data were uploaded before trying to finish the session.
payload_too_largeVoidThe request payload must be at most 150 MiB.
content_hash_mismatchVoidThe content received by the Dropbox server in this call does not match the provided content hash.
encryption_not_supportedVoidThe file is required to be encrypted, which is not supported in our public API.
See also general errors.

/upload_session/finish_batch


Description

This route helps you commit many files at once into a user's Dropbox. Use upload_session/start and upload_session/append:2 to upload file contents. We recommend uploading many files in parallel to increase throughput. Once the file contents have been uploaded, rather than calling upload_session/finish, use this route to finish all your upload sessions in a single request. UploadSessionStartArg.close or UploadSessionAppendArg.close needs to be true for the last upload_session/start or upload_session/append:2 call of each upload session. The maximum size of a file one can upload to an upload session is 350 GiB. We allow up to 1000 entries in a single request. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

URL Structure
https://api.dropboxapi.com/2/files/upload_session/finish_batch_v2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/upload_session/finish_batch_v2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"entries\":[{\"commit\":{\"autorename\":true,\"mode\":\"add\",\"mute\":false,\"path\":\"/Homework/math/Matrices.txt\",\"strict_conflict\":false},\"cursor\":{\"offset\":0,\"session_id\":\"1234faaf0678bcde\"}}]}"
Parameters
{
    "entries": [
        {
            "commit": {
                "autorename": true,
                "mode": "add",
                "mute": false,
                "path": "/Homework/math/Matrices.txt",
                "strict_conflict": false
            },
            "cursor": {
                "offset": 0,
                "session_id": "1234faaf0678bcde"
            }
        }
    ]
}
Example: multiple
{
    "entries": [
        {
            "commit": {
                "autorename": true,
                "mode": "add",
                "mute": false,
                "path": "/Homework/math/Matrices.txt",
                "strict_conflict": false
            },
            "cursor": {
                "offset": 0,
                "session_id": "1234faaf0678bcde"
            }
        },
        {
            "commit": {
                "autorename": true,
                "mode": "add",
                "mute": false,
                "path": "/Homework/math/Vectors.txt",
                "strict_conflict": false
            },
            "cursor": {
                "offset": 1073741824,
                "session_id": "8dd9d57374911153"
            }
        }
    ]
}
UploadSessionFinishBatchArg
entriesList of (, max_items=1000)Commit information for each file in the batch.
Returns
{
    "entries": [
        {
            ".tag": "success",
            "client_modified": "2015-05-12T15:50:38Z",
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "file_lock_info": {
                "created": "2015-05-12T15:50:38Z",
                "is_lockholder": true,
                "lockholder_name": "Imaginary User"
            },
            "has_explicit_shared_members": false,
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "is_downloadable": true,
            "name": "Prime_Numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "path_lower": "/homework/math/prime_numbers.txt",
            "property_groups": [
                {
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ],
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                }
            ],
            "rev": "a1c10ce0dd78",
            "server_modified": "2015-05-12T15:50:38Z",
            "sharing_info": {
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "parent_shared_folder_id": "84528192421",
                "read_only": true
            },
            "size": 7212
        }
    ]
}
UploadSessionFinishBatchResult
entriesList of ()Each entry in UploadSessionFinishBatchArg.entries will appear at the same position inside UploadSessionFinishBatchResult.entries.
Errors
No endpoint-specific errors.
See also general errors.

/upload_session/finish_batch/check


Description

Returns the status of an asynchronous job for upload_session/finish_batch. If success, it returns list of result for each entry.

URL Structure
https://api.dropboxapi.com/2/files/upload_session/finish_batch/check
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/upload_session/finish_batch/check \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"async_job_id\":\"34g93hh34h04y384084\"}"
Parameters
{
    "async_job_id": "34g93hh34h04y384084"
}
PollArg
Arguments for methods that poll the status of an asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Returns
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "client_modified": "2015-05-12T15:50:38Z",
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
            "file_lock_info": {
                "created": "2015-05-12T15:50:38Z",
                "is_lockholder": true,
                "lockholder_name": "Imaginary User"
            },
            "has_explicit_shared_members": false,
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "is_downloadable": true,
            "name": "Prime_Numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "path_lower": "/homework/math/prime_numbers.txt",
            "property_groups": [
                {
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ],
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
                }
            ],
            "rev": "a1c10ce0dd78",
            "server_modified": "2015-05-12T15:50:38Z",
            "sharing_info": {
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "parent_shared_folder_id": "84528192421",
                "read_only": true
            },
            "size": 7212
        }
    ]
}
Example: in_progress
{
    ".tag": "in_progress"
}
UploadSessionFinishBatchJobStatus (union)
in_progressVoidThe asynchronous job is still in progress.
completeThe upload_session/finish_batch has finished.
Errors
Example: invalid_async_job_id
{
    "error": {
        ".tag": "invalid_async_job_id"
    },
    "error_summary": "invalid_async_job_id/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
PollError (open union)
Error returned by methods for polling the status of asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
invalid_async_job_idVoidThe job ID is invalid.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/upload_session/start


Description

Upload sessions allow you to upload a single file in one or more requests, for example where the size of the file is greater than 150 MiB. This call starts a new upload session with the given data. You can then use upload_session/append:2 to add more data and upload_session/finish to save all the data to a file in Dropbox. A single request should not upload more than 150 MiB. The maximum size of a file one can upload to an upload session is 350 GiB. An upload session can be used for a maximum of 7 days. Attempting to use an UploadSessionStartResult.session_id with upload_session/append:2 or upload_session/finish more than 7 days after its creation will return a UploadSessionLookupError.not_found. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page. By default, upload sessions require you to send content of the file in sequential order via consecutive upload_session/start, upload_session/append:2, upload_session/finish calls. For better performance, you can instead optionally use a UploadSessionType.concurrent upload session. To start a new concurrent session, set UploadSessionStartArg.session_type to UploadSessionType.concurrent. After that, you can send file data in concurrent upload_session/append:2 requests. Finally finish the session with upload_session/finish. There are couple of constraints with concurrent sessions to make them work. You can not send data with upload_session/start or upload_session/finish call, only with upload_session/append:2 call. Also data uploaded in upload_session/append:2 call must be multiple of 4194304 bytes (except for last upload_session/append:2 with UploadSessionStartArg.close to true, that may contain any remaining data).

URL Structure
https://content.dropboxapi.com/2/files/upload_session/start
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
Content-upload
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/upload_session/start \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"close\":false}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "close": false
}
UploadSessionStartArg
closeBooleanIf true, the current session will be closed, at which point you won't be able to call upload_session/append:2 anymore with the current session. The default for this field is False.
session_type?Type of upload session you want to start. If not specified, default is UploadSessionType.sequential. This field is optional.
content_hash String(min_length=64, max_length=64)?A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page. This field is optional.
Returns
{
    "session_id": "1234faaf0678bcde"
}
UploadSessionStartResult
session_idStringA unique identifier for the upload session. Pass this to upload_session/append:2 and upload_session/finish.
Errors
Example: concurrent_session_data_not_allowed
{
    "error": {
        ".tag": "concurrent_session_data_not_allowed"
    },
    "error_summary": "concurrent_session_data_not_allowed/..."
}
Example: concurrent_session_close_not_allowed
{
    "error": {
        ".tag": "concurrent_session_close_not_allowed"
    },
    "error_summary": "concurrent_session_close_not_allowed/..."
}
Example: payload_too_large
{
    "error": {
        ".tag": "payload_too_large"
    },
    "error_summary": "payload_too_large/..."
}
Example: content_hash_mismatch
{
    "error": {
        ".tag": "content_hash_mismatch"
    },
    "error_summary": "content_hash_mismatch/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UploadSessionStartError (open union)
concurrent_session_data_not_allowedVoidUploading data not allowed when starting concurrent upload session.
concurrent_session_close_not_allowedVoidCan not start a closed concurrent upload session.
payload_too_largeVoidThe request payload must be at most 150 MiB.
content_hash_mismatchVoidThe content received by the Dropbox server in this call does not match the provided content hash.
See also general errors.

/upload_session/start_batch


Description

This route starts batch of upload_sessions. Please refer to `upload_session/start` usage. Calls to this endpoint will count as data transport calls for any Dropbox Business teams with a limit on the number of data transport calls allowed per month. For more information, see the Data transport limit page.

URL Structure
https://api.dropboxapi.com/2/files/upload_session/start_batch
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/upload_session/start_batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"num_sessions\":1}"
Parameters
{
    "num_sessions": 1
}
UploadSessionStartBatchArg
num_sessionsUInt64(min=1, max=1000)The number of upload sessions to start.
session_type?Type of upload session you want to start. If not specified, default is UploadSessionType.sequential. This field is optional.
Returns
{
    "session_ids": [
        "1234faaf0678bcde"
    ]
}
UploadSessionStartBatchResult
session_ids List of (String)A List of unique identifiers for the upload session. Pass each session_id to upload_session/append:2 and upload_session/finish.
Errors
No endpoint-specific errors.
See also general errors.

openid

/userinfo


PREVIEW - may change or disappear without notice
Description

This route is used for refreshing the info that is found in the id_token during the OIDC flow. This route doesn't require any arguments and will use the scopes approved for the given access token.

URL Structure
https://api.dropboxapi.com/2/openid/userinfo
Authentication
User Authentication
Endpoint format
RPC
Required Scope
openid
Parameters
No parameters.
Returns
UserInfoResult
family_name String?Last name of user. This field is optional.
given_name String?First name of user. This field is optional.
email String?Email address of user. This field is optional.
email_verified Boolean?If user is email verified. This field is optional.
issStringIssuer of token (in this case Dropbox). The default for this field is "".
subStringAn identifier for the user. This is the Dropbox account_id, a string value such as dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc. The default for this field is "".
Errors
UserInfoError (open union)
openid_error
See also general errors.

paper

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 :link:`Paper Migration Guide https://www.dropbox.com/lp/developers/reference/paper-migration-guide`.

sharing

This namespace contains endpoints and data types for creating and managing shared links and shared folders.

/add_file_member


Description

Adds specified members to a file.

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

URL Structure
https://api.dropboxapi.com/2/sharing/add_file_member
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/add_file_member \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"access_level\":\"viewer\",\"add_message_as_comment\":false,\"custom_message\":\"This is a custom message about ACME.doc\",\"file\":\"id:3kmLmQFnf1AAAAAAAAAAAw\",\"members\":[{\".tag\":\"email\",\"email\":\"justin@example.com\"}],\"quiet\":false}"
Parameters
{
    "access_level": "viewer",
    "add_message_as_comment": false,
    "custom_message": "This is a custom message about ACME.doc",
    "file": "id:3kmLmQFnf1AAAAAAAAAAAw",
    "members": [
        {
            ".tag": "email",
            "email": "justin@example.com"
        }
    ],
    "quiet": false
}
AddFileMemberArgs
Arguments for add_file_member.
fileString(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")File to which to add members.
membersList of ()Members to add. Note that even an email address is given, this may result in a user being directly added to the membership if that email is the user's main account email.
custom_message String?Message to send to added members in their invitation. This field is optional.
quietBooleanWhether added members should be notified via email and device notifications of their invitation. The default for this field is False.
access_levelAccessLevel union object, describing what access level we want to give new members. The default for this union is viewer.
add_message_as_commentBooleanIf the custom message should be added as a comment on the file. The default for this field is False.
fp_sealed_resultinternal String?Field is only returned for "internal" callers. The FingerprintJS Sealed Client Result value This field is optional.
Returns
List of (FileMemberActionResult)
Per-member result for add_file_member.
memberOne of specified input members.
resultThe outcome of the action on this member.
sckey_sha1 String?The SHA-1 encrypted shared content key. This field is optional.
invitation_signature List of (String)?The sharing sender-recipient invitation signatures for the input member_id. A member_id can be a group and thus have multiple users and multiple invitation signatures. This field is optional.
Errors
Example: rate_limit
{
    "error": {
        ".tag": "rate_limit"
    },
    "error_summary": "rate_limit/..."
}
Example: invalid_comment
{
    "error": {
        ".tag": "invalid_comment"
    },
    "error_summary": "invalid_comment/..."
}
Example: banned_member
{
    "error": {
        ".tag": "banned_member"
    },
    "error_summary": "banned_member/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
AddFileMemberError (open union)
Errors for add_file_member.
user_error
access_error
rate_limitVoidThe user has reached the rate limit for invitations.
invalid_commentVoidThe custom message did not pass comment permissions checks.
banned_memberVoidThe current user has been banned for abuse reasons.
See also general errors.

/add_folder_member


Description

Allows an owner or editor (if the ACL update policy allows) of a shared folder to add another member. For the new member to get access to all the functionality for this folder, you will need to call mount_folder on their behalf.

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

URL Structure
https://api.dropboxapi.com/2/sharing/add_folder_member
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/add_folder_member \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"custom_message\":\"Documentation for launch day\",\"members\":[{\"access_level\":\"editor\",\"member\":{\".tag\":\"email\",\"email\":\"justin@example.com\"}},{\"access_level\":\"viewer\",\"member\":{\".tag\":\"dropbox_id\",\"dropbox_id\":\"dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q\"}}],\"quiet\":false,\"shared_folder_id\":\"84528192421\"}"
Parameters
{
    "custom_message": "Documentation for launch day",
    "members": [
        {
            "access_level": "editor",
            "member": {
                ".tag": "email",
                "email": "justin@example.com"
            }
        },
        {
            "access_level": "viewer",
            "member": {
                ".tag": "dropbox_id",
                "dropbox_id": "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"
            }
        }
    ],
    "quiet": false,
    "shared_folder_id": "84528192421"
}
AddFolderMemberArg
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
membersList of ()The intended list of members to add. Added members will receive invites to join the shared folder.
quietBooleanWhether added members should be notified via email and device notifications of their invite. The default for this field is False.
custom_message String(min_length=1)?Optional message to display to added members in their invitation. This field is optional.
fp_sealed_resultinternal String?Field is only returned for "internal" callers. The FingerprintJS Sealed Client Result value This field is optional.
Returns
No return values.
Errors
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: member
{
    "error": {
        ".tag": "bad_member",
        "bad_member": {
            ".tag": "invalid_dropbox_id",
            "invalid_dropbox_id": "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"
        }
    },
    "error_summary": "bad_member/invalid_dropbox_id/..."
}
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: banned_member
{
    "error": {
        ".tag": "banned_member"
    },
    "error_summary": "banned_member/..."
}
Example: cant_share_outside_team
{
    "error": {
        ".tag": "cant_share_outside_team"
    },
    "error_summary": "cant_share_outside_team/..."
}
Example: rate_limit
{
    "error": {
        ".tag": "rate_limit"
    },
    "error_summary": "rate_limit/..."
}
Example: too_many_invitees
{
    "error": {
        ".tag": "too_many_invitees"
    },
    "error_summary": "too_many_invitees/..."
}
Example: insufficient_plan
{
    "error": {
        ".tag": "insufficient_plan"
    },
    "error_summary": "insufficient_plan/..."
}
Example: team_folder
{
    "error": {
        ".tag": "team_folder"
    },
    "error_summary": "team_folder/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: invalid_shared_folder
{
    "error": {
        ".tag": "invalid_shared_folder"
    },
    "error_summary": "invalid_shared_folder/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
AddFolderMemberError (open union)
access_errorUnable to access shared folder.
email_unverifiedVoidThis user's email address is not verified. This functionality is only available on accounts with a verified email address. Users can verify their email address here.
banned_memberVoidThe current user has been banned.
bad_memberAddFolderMemberArg.members contains a bad invitation recipient.
cant_share_outside_teamVoidYour team policy does not allow sharing outside of the team.
too_many_membersUInt64The value is the member limit that was reached.
too_many_pending_invitesUInt64The value is the pending invite limit that was reached.
rate_limitVoidThe current user has hit the limit of invites they can send per day. Try again in 24 hours.
too_many_inviteesVoidThe current user is trying to share with too many people at once.
insufficient_planVoidThe current user's account doesn't support this action. An example of this is when adding a read-only member. This action can only be performed by users that have upgraded to a Pro or Business plan.
team_folderVoidThis action cannot be performed on a team shared folder.
no_permissionVoidThe current user does not have permission to perform this action.
invalid_shared_folderdeprecatedVoidField is deprecated. Invalid shared folder error will be returned as an access_error.
See also general errors.

/check_job_status


Description

Returns the status of an asynchronous job.

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

URL Structure
https://api.dropboxapi.com/2/sharing/check_job_status
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/check_job_status \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"async_job_id\":\"34g93hh34h04y384084\"}"
Parameters
{
    "async_job_id": "34g93hh34h04y384084"
}
PollArg
Arguments for methods that poll the status of an asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Returns
Example: in_progress
{
    ".tag": "in_progress"
}
Example: complete
{
    ".tag": "complete"
}
JobStatus (union)
in_progressVoidThe asynchronous job is still in progress.
completeVoidThe asynchronous job has finished.
failedThe asynchronous job returned an error.
Errors
Example: invalid_async_job_id
{
    "error": {
        ".tag": "invalid_async_job_id"
    },
    "error_summary": "invalid_async_job_id/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
PollError (open union)
Error returned by methods for polling the status of asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
invalid_async_job_idVoidThe job ID is invalid.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/check_remove_member_job_status


Description

Returns the status of an asynchronous job for sharing a folder.

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

URL Structure
https://api.dropboxapi.com/2/sharing/check_remove_member_job_status
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/check_remove_member_job_status \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"async_job_id\":\"34g93hh34h04y384084\"}"
Parameters
{
    "async_job_id": "34g93hh34h04y384084"
}
PollArg
Arguments for methods that poll the status of an asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Returns
{
    ".tag": "complete"
}
Example: in_progress
{
    ".tag": "in_progress"
}
RemoveMemberJobStatus (union)
in_progressVoidThe asynchronous job is still in progress.
completeRemoving the folder member has finished. The value is information about whether the member has another form of access.
failed
Errors
Example: invalid_async_job_id
{
    "error": {
        ".tag": "invalid_async_job_id"
    },
    "error_summary": "invalid_async_job_id/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
PollError (open union)
Error returned by methods for polling the status of asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
invalid_async_job_idVoidThe job ID is invalid.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/check_share_job_status


Description

Returns the status of an asynchronous job for sharing a folder.

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

URL Structure
https://api.dropboxapi.com/2/sharing/check_share_job_status
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/check_share_job_status \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"async_job_id\":\"34g93hh34h04y384084\"}"
Parameters
{
    "async_job_id": "34g93hh34h04y384084"
}
PollArg
Arguments for methods that poll the status of an asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)Id of the asynchronous job. This is the value of a response returned from the method that launched the job.
Returns
{
    ".tag": "complete",
    "access_inheritance": {
        ".tag": "inherit"
    },
    "access_type": {
        ".tag": "owner"
    },
    "folder_id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_inside_team_folder": false,
    "is_team_folder": false,
    "link_metadata": {
        "audience_options": [
            {
                ".tag": "public"
            },
            {
                ".tag": "team"
            },
            {
                ".tag": "members"
            }
        ],
        "current_audience": {
            ".tag": "public"
        },
        "link_permissions": [
            {
                "action": {
                    ".tag": "change_audience"
                },
                "allow": true
            }
        ],
        "password_protected": false,
        "url": ""
    },
    "name": "dir",
    "path_lower": "/dir",
    "permissions": [],
    "policy": {
        "acl_update_policy": {
            ".tag": "owner"
        },
        "member_policy": {
            ".tag": "anyone"
        },
        "resolved_member_policy": {
            ".tag": "team"
        },
        "shared_link_policy": {
            ".tag": "anyone"
        }
    },
    "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
    "shared_folder_id": "84528192421",
    "time_invited": "2016-01-20T00:00:00Z"
}
Example: in_progress
{
    ".tag": "in_progress"
}
ShareFolderJobStatus (union)
in_progressVoidThe asynchronous job is still in progress.
completeThe share job has finished. The value is the metadata for the folder.
failed
Errors
Example: invalid_async_job_id
{
    "error": {
        ".tag": "invalid_async_job_id"
    },
    "error_summary": "invalid_async_job_id/..."
}
Example: internal_error
{
    "error": {
        ".tag": "internal_error"
    },
    "error_summary": "internal_error/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
PollError (open union)
Error returned by methods for polling the status of asynchronous job. This datatype comes from an imported namespace originally defined in the async namespace.
invalid_async_job_idVoidThe job ID is invalid.
internal_errorVoidSomething went wrong with the job on Dropbox's end. You'll need to verify that the action you were taking succeeded, and if not, try again. This should happen very rarely.
See also general errors.

/create_shared_link_with_settings


Description

Create a shared link with custom settings. If no settings are given then the default visibility is RequestedVisibility.public (The resolved visibility, though, may depend on other aspects such as team and shared folder settings).

URL Structure
https://api.dropboxapi.com/2/sharing/create_shared_link_with_settings
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/create_shared_link_with_settings \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/Prime_Numbers.txt\",\"settings\":{\"access\":\"viewer\",\"allow_download\":true,\"audience\":\"public\",\"requested_visibility\":\"public\"}}"
Parameters
{
    "path": "/Prime_Numbers.txt",
    "settings": {
        "access": "viewer",
        "allow_download": true,
        "audience": "public",
        "requested_visibility": "public"
    }
}
CreateSharedLinkWithSettingsArg
pathString(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")The path to be shared by the shared link.
settings?The requested settings for the newly created shared link. This field is optional.
Returns
{
    ".tag": "file",
    "client_modified": "2015-05-12T15:50:38Z",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "link_permissions": {
        "allow_comments": true,
        "allow_download": true,
        "audience_options": [
            {
                "allowed": true,
                "audience": {
                    ".tag": "public"
                }
            },
            {
                "allowed": false,
                "audience": {
                    ".tag": "team"
                }
            },
            {
                "allowed": true,
                "audience": {
                    ".tag": "no_one"
                }
            }
        ],
        "can_allow_download": true,
        "can_disallow_download": false,
        "can_remove_expiry": false,
        "can_remove_password": true,
        "can_revoke": false,
        "can_set_expiry": false,
        "can_set_password": true,
        "can_use_extended_sharing_controls": false,
        "require_password": false,
        "resolved_visibility": {
            ".tag": "public"
        },
        "revoke_failure_reason": {
            ".tag": "owner_only"
        },
        "team_restricts_comments": true,
        "visibility_policies": [
            {
                "allowed": true,
                "policy": {
                    ".tag": "public"
                },
                "resolved_policy": {
                    ".tag": "public"
                }
            },
            {
                "allowed": true,
                "policy": {
                    ".tag": "password"
                },
                "resolved_policy": {
                    ".tag": "password"
                }
            }
        ]
    },
    "name": "Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "size": 7212,
    "team_member_info": {
        "display_name": "Roger Rabbit",
        "member_id": "dbmid:abcd1234",
        "team_info": {
            "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
            "name": "Acme, Inc."
        }
    },
    "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
}
{
    ".tag": "folder",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "link_permissions": {
        "allow_comments": true,
        "allow_download": true,
        "audience_options": [
            {
                "allowed": true,
                "audience": {
                    ".tag": "public"
                }
            },
            {
                "allowed": false,
                "audience": {
                    ".tag": "team"
                }
            },
            {
                "allowed": true,
                "audience": {
                    ".tag": "no_one"
                }
            }
        ],
        "can_allow_download": true,
        "can_disallow_download": false,
        "can_remove_expiry": false,
        "can_remove_password": true,
        "can_revoke": false,
        "can_set_expiry": false,
        "can_set_password": true,
        "can_use_extended_sharing_controls": false,
        "require_password": false,
        "resolved_visibility": {
            ".tag": "public"
        },
        "revoke_failure_reason": {
            ".tag": "owner_only"
        },
        "team_restricts_comments": true,
        "visibility_policies": [
            {
                "allowed": true,
                "policy": {
                    ".tag": "public"
                },
                "resolved_policy": {
                    ".tag": "public"
                }
            },
            {
                "allowed": true,
                "policy": {
                    ".tag": "password"
                },
                "resolved_policy": {
                    ".tag": "password"
                }
            }
        ]
    },
    "name": "Math",
    "path_lower": "/homework/math",
    "team_member_info": {
        "display_name": "Roger Rabbit",
        "member_id": "dbmid:abcd1234",
        "team_info": {
            "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
            "name": "Acme, Inc."
        }
    },
    "url": "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
}
SharedLinkMetadata (datatype with subtypes)
The metadata of a shared link.
file
folder
Errors
Example: email_not_verified
{
    "error": {
        ".tag": "email_not_verified"
    },
    "error_summary": "email_not_verified/..."
}
Example: access_denied
{
    "error": {
        ".tag": "access_denied"
    },
    "error_summary": "access_denied/..."
}
Example: banned_member
{
    "error": {
        ".tag": "banned_member"
    },
    "error_summary": "banned_member/..."
}
CreateSharedLinkWithSettingsError (union)
path
email_not_verifiedVoidThis user's email address is not verified. This functionality is only available on accounts with a verified email address. Users can verify their email address here.
shared_link_already_exists?The shared link already exists. You can call list_shared_links to get the existing link, or use the provided metadata if it is returned. This field is optional.
settings_errorThere is an error with the given settings.
access_deniedVoidThe user is not allowed to create a shared link to the specified file. For example, this can occur if the file is restricted or if the user's links are banned.
banned_memberVoidThe current user has been banned for abuse reasons.
See also general errors.

/get_file_metadata


Description

Returns shared file metadata.

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

URL Structure
https://api.dropboxapi.com/2/sharing/get_file_metadata
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/get_file_metadata \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"actions\":[],\"file\":\"id:3kmLmQFnf1AAAAAAAAAAAw\"}"
Parameters
{
    "actions": [],
    "file": "id:3kmLmQFnf1AAAAAAAAAAAw"
}
GetFileMetadataArg
Arguments of get_file_metadata.
fileString(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")The file to query.
actionsList of ()?A list of `FileAction`s corresponding to `FilePermission`s that should appear in the response's SharedFileMetadata.permissions field describing the actions the authenticated user can perform on the file. This field is optional.
Returns
{
    "access_type": {
        ".tag": "viewer"
    },
    "id": "id:3kmLmQFnf1AAAAAAAAAAAw",
    "name": "file.txt",
    "owner_display_names": [
        "Jane Doe"
    ],
    "owner_team": {
        "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
        "name": "Acme, Inc."
    },
    "path_display": "/dir/file.txt",
    "path_lower": "/dir/file.txt",
    "permissions": [],
    "policy": {
        "acl_update_policy": {
            ".tag": "owner"
        },
        "member_policy": {
            ".tag": "anyone"
        },
        "resolved_member_policy": {
            ".tag": "team"
        },
        "shared_link_policy": {
            ".tag": "anyone"
        }
    },
    "preview_url": "https://www.dropbox.com/scl/fi/fir9vjelf",
    "time_invited": "2016-01-20T00:00:00Z"
}
SharedFileMetadata
Properties of the shared file.
idString(min_length=4, pattern="id:.+")The ID of the file.
nameStringThe name of this file.
policyPolicies governing this shared file.
preview_urlStringURL for displaying a web preview of the shared file.
access_type?The current user's access level for this shared file. This field is optional.
expected_link_metadata?The expected metadata of the link associated for the file when it is first shared. Absent if the link already exists. This is for an unreleased feature so it may not be returned yet. This field is optional.
link_metadata?The metadata of the link associated for the file. This is for an unreleased feature so it may not be returned yet. This field is optional.
owner_display_names List of (String)?The display names of the users that own the file. If the file is part of a team folder, the display names of the team admins are also included. Absent if the owner display names cannot be fetched. This field is optional.
owner_team?The team that owns the file. This field is not present if the file is not owned by a team. This field is optional.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")?The ID of the parent shared folder. This field is present only if the file is contained within a shared folder. This field is optional.
path_display String?The cased path to be used for display purposes only. In rare instances the casing will not correctly match the user's filesystem, but this behavior will match the path provided in the Core API v1. Absent for unmounted files. This field is optional.
path_lower String?The lower-case full path of this file. Absent for unmounted files. This field is optional.
permissionsList of ()?The sharing permissions that requesting user has on this file. This corresponds to the entries given in GetFileMetadataBatchArg.actions or GetFileMetadataArg.actions. This field is optional.
time_invited Timestamp(format="%Y-%m-%dT%H:%M:%SZ")?Timestamp indicating when the current user was invited to this shared file. If the user was not invited to the shared file, the timestamp will indicate when the user was invited to the parent shared folder. This value may be absent. This field is optional.
Errors
GetFileMetadataError (open union)
Error result for get_file_metadata.
user_error
access_error
See also general errors.

/get_file_metadata/batch


Description

Returns shared file metadata.

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

URL Structure
https://api.dropboxapi.com/2/sharing/get_file_metadata/batch
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/get_file_metadata/batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"actions\":[],\"files\":[\"id:3kmLmQFnf1AAAAAAAAAAAw\",\"id:VvTaJu2VZzAAAAAAAAAADQ\"]}"
Parameters
{
    "actions": [],
    "files": [
        "id:3kmLmQFnf1AAAAAAAAAAAw",
        "id:VvTaJu2VZzAAAAAAAAAADQ"
    ]
}
GetFileMetadataBatchArg
Arguments of get_file_metadata/batch.
files List of (String(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?"), max_items=100)The files to query.
actionsList of ()?A list of `FileAction`s corresponding to `FilePermission`s that should appear in the response's SharedFileMetadata.permissions field describing the actions the authenticated user can perform on the file. This field is optional.
Returns
List of (GetFileMetadataBatchResult)
Per file results of get_file_metadata/batch.
fileString(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")This is the input file identifier corresponding to one of GetFileMetadataBatchArg.files.
resultThe result for this particular file.
Errors
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SharingUserError (open union)
User account had a problem preventing this action.
email_unverifiedVoidThis user's email address is not verified. This functionality is only available on accounts with a verified email address. Users can verify their email address here.
See also general errors.

/get_folder_metadata


Description

Returns shared folder metadata by its folder ID.

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

URL Structure
https://api.dropboxapi.com/2/sharing/get_folder_metadata
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/get_folder_metadata \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"actions\":[],\"shared_folder_id\":\"84528192421\"}"
Parameters
{
    "actions": [],
    "shared_folder_id": "84528192421"
}
GetMetadataArgs
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
actionsList of ()?A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the response's SharedFolderMetadata.permissions field describing the actions the authenticated user can perform on the folder. This field is optional.
Returns
{
    "access_inheritance": {
        ".tag": "inherit"
    },
    "access_type": {
        ".tag": "owner"
    },
    "folder_id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_inside_team_folder": false,
    "is_team_folder": false,
    "link_metadata": {
        "audience_options": [
            {
                ".tag": "public"
            },
            {
                ".tag": "team"
            },
            {
                ".tag": "members"
            }
        ],
        "current_audience": {
            ".tag": "public"
        },
        "link_permissions": [
            {
                "action": {
                    ".tag": "change_audience"
                },
                "allow": true
            }
        ],
        "password_protected": false,
        "url": ""
    },
    "name": "dir",
    "path_lower": "/dir",
    "permissions": [],
    "policy": {
        "acl_update_policy": {
            ".tag": "owner"
        },
        "member_policy": {
            ".tag": "anyone"
        },
        "resolved_member_policy": {
            ".tag": "team"
        },
        "shared_link_policy": {
            ".tag": "anyone"
        }
    },
    "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
    "shared_folder_id": "84528192421",
    "time_invited": "2016-01-20T00:00:00Z"
}
SharedFolderMetadata
The metadata which includes basic information about the shared folder.
access_typeThe current user's access level for this shared folder.
is_inside_team_folderBooleanWhether this folder is inside of a team folder.
is_team_folderBooleanWhether this folder is a team folder.
nameStringThe name of the this shared folder.
policyPolicies governing this shared folder.
preview_urlStringURL for displaying a web preview of the shared folder.
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID of the shared folder.
time_invitedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")Timestamp indicating when the current user was invited to this shared folder.
owner_display_names List of (String)?The display names of the users that own the folder. If the folder is part of a team folder, the display names of the team admins are also included. Absent if the owner display names cannot be fetched. This field is optional.
owner_team?The team that owns the folder. This field is not present if the folder is not owned by a team. This field is optional.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")?The ID of the parent shared folder. This field is present only if the folder is contained within another shared folder. This field is optional.
path_display String?The full path of this shared folder. Absent for unmounted folders. This field is optional.
path_lower String?The lower-cased full path of this shared folder. Absent for unmounted folders. This field is optional.
parent_folder_name String?Display name for the parent folder. This field is optional.
link_metadata?The metadata of the shared content link to this shared folder. Absent if there is no link on the folder. This is for an unreleased feature so it may not be returned yet. This field is optional.
permissionsList of ()?Actions the current user may perform on the folder and its contents. The set of permissions corresponds to the FolderActions in the request. This field is optional.
access_inheritanceWhether the folder inherits its members from its parent. The default for this union is inherit.
folder_id String(min_length=4, pattern="id:.+")?The ID of the content. This field is optional.
Errors
Example: invalid_id
{
    "error": {
        ".tag": "invalid_id"
    },
    "error_summary": "invalid_id/..."
}
Example: not_a_member
{
    "error": {
        ".tag": "not_a_member"
    },
    "error_summary": "not_a_member/..."
}
Example: invalid_member
{
    "error": {
        ".tag": "invalid_member"
    },
    "error_summary": "invalid_member/..."
}
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: unmounted
{
    "error": {
        ".tag": "unmounted"
    },
    "error_summary": "unmounted/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SharedFolderAccessError (open union)
There is an error accessing the shared folder.
invalid_idVoidThis shared folder ID is invalid.
not_a_memberVoidThe user is not a member of the shared folder thus cannot access it.
invalid_memberVoidThe user does not exist or their account is disabled.
email_unverifieddeprecatedVoidField is deprecated. Never set.
unmountedVoidThe shared folder is unmounted.
See also general errors.

/get_shared_link_file


Description

Download the shared link's file from a user's Dropbox.

URL Structure
https://content.dropboxapi.com/2/sharing/get_shared_link_file
Authentication
User Authentication, App Authentication
Endpoint format
Content-download
Required Scope
sharing.read
Example
Get app key and secret for:
curl -X POST https://content.dropboxapi.com/2/sharing/get_shared_link_file \
    --header "Authorization: Basic <get app key and secret>" \
    --header "Dropbox-API-Arg: {\"path\":\"/Prime_Numbers.txt\",\"url\":\"https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0\"}"
Parameters
{
    "path": "/Prime_Numbers.txt",
    "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
}
GetSharedLinkMetadataArg
urlStringURL of the shared link.
path String(pattern="/(.|[\r\n])*")?If the shared link is to a folder, this parameter can be used to retrieve the metadata for a specific file or sub-folder in this folder. A relative path should be used. This field is optional.
link_password String?If the shared link has a password, this parameter can be used. This field is optional.
Returns
{
    ".tag": "file",
    "client_modified": "2015-05-12T15:50:38Z",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "link_permissions": {
        "allow_comments": true,
        "allow_download": true,
        "audience_options": [
            {
                "allowed": true,
                "audience": {
                    ".tag": "public"
                }
            },
            {
                "allowed": false,
                "audience": {
                    ".tag": "team"
                }
            },
            {
                "allowed": true,
                "audience": {
                    ".tag": "no_one"
                }
            }
        ],
        "can_allow_download": true,
        "can_disallow_download": false,
        "can_remove_expiry": false,
        "can_remove_password": true,
        "can_revoke": false,
        "can_set_expiry": false,
        "can_set_password": true,
        "can_use_extended_sharing_controls": false,
        "require_password": false,
        "resolved_visibility": {
            ".tag": "public"
        },
        "revoke_failure_reason": {
            ".tag": "owner_only"
        },
        "team_restricts_comments": true,
        "visibility_policies": [
            {
                "allowed": true,
                "policy": {
                    ".tag": "public"
                },
                "resolved_policy": {
                    ".tag": "public"
                }
            },
            {
                "allowed": true,
                "policy": {
                    ".tag": "password"
                },
                "resolved_policy": {
                    ".tag": "password"
                }
            }
        ]
    },
    "name": "Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "size": 7212,
    "team_member_info": {
        "display_name": "Roger Rabbit",
        "member_id": "dbmid:abcd1234",
        "team_info": {
            "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
            "name": "Acme, Inc."
        }
    },
    "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
}
{
    ".tag": "folder",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "link_permissions": {
        "allow_comments": true,
        "allow_download": true,
        "audience_options": [
            {
                "allowed": true,
                "audience": {
                    ".tag": "public"
                }
            },
            {
                "allowed": false,
                "audience": {
                    ".tag": "team"
                }
            },
            {
                "allowed": true,
                "audience": {
                    ".tag": "no_one"
                }
            }
        ],
        "can_allow_download": true,
        "can_disallow_download": false,
        "can_remove_expiry": false,
        "can_remove_password": true,
        "can_revoke": false,
        "can_set_expiry": false,
        "can_set_password": true,
        "can_use_extended_sharing_controls": false,
        "require_password": false,
        "resolved_visibility": {
            ".tag": "public"
        },
        "revoke_failure_reason": {
            ".tag": "owner_only"
        },
        "team_restricts_comments": true,
        "visibility_policies": [
            {
                "allowed": true,
                "policy": {
                    ".tag": "public"
                },
                "resolved_policy": {
                    ".tag": "public"
                }
            },
            {
                "allowed": true,
                "policy": {
                    ".tag": "password"
                },
                "resolved_policy": {
                    ".tag": "password"
                }
            }
        ]
    },
    "name": "Math",
    "path_lower": "/homework/math",
    "team_member_info": {
        "display_name": "Roger Rabbit",
        "member_id": "dbmid:abcd1234",
        "team_info": {
            "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
            "name": "Acme, Inc."
        }
    },
    "url": "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
}
SharedLinkMetadata (datatype with subtypes)
The metadata of a shared link.
file
folder
Errors
Example: shared_link_not_found
{
    "error": {
        ".tag": "shared_link_not_found"
    },
    "error_summary": "shared_link_not_found/..."
}
Example: shared_link_access_denied
{
    "error": {
        ".tag": "shared_link_access_denied"
    },
    "error_summary": "shared_link_access_denied/..."
}
Example: unsupported_link_type
{
    "error": {
        ".tag": "unsupported_link_type"
    },
    "error_summary": "unsupported_link_type/..."
}
Example: unsupported_parameter_field
{
    "error": {
        ".tag": "unsupported_parameter_field"
    },
    "error_summary": "unsupported_parameter_field/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: shared_link_is_directory
{
    "error": {
        ".tag": "shared_link_is_directory"
    },
    "error_summary": "shared_link_is_directory/..."
}
GetSharedLinkFileError (union)
shared_link_not_foundVoidThe shared link wasn't found.
shared_link_access_deniedVoidThe caller is not allowed to access this shared link.
unsupported_link_typeVoidThis type of link is not supported; use files.export instead.
unsupported_parameter_fieldVoidPrivate shared links do not support `path` or `link_password` parameter fields.
shared_link_is_directoryVoidDirectories cannot be retrieved by this endpoint.
See also general errors.

/get_shared_link_metadata


Description

Get the shared link's metadata.

URL Structure
https://api.dropboxapi.com/2/sharing/get_shared_link_metadata
Authentication
User Authentication, App Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get app key and secret for:
curl -X POST https://api.dropboxapi.com/2/sharing/get_shared_link_metadata \
    --header "Authorization: Basic <get app key and secret>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/Prime_Numbers.txt\",\"url\":\"https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0\"}"
Parameters
{
    "path": "/Prime_Numbers.txt",
    "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
}
GetSharedLinkMetadataArg
urlStringURL of the shared link.
path String(pattern="/(.|[\r\n])*")?If the shared link is to a folder, this parameter can be used to retrieve the metadata for a specific file or sub-folder in this folder. A relative path should be used. This field is optional.
link_password String?If the shared link has a password, this parameter can be used. This field is optional.
Returns
{
    ".tag": "file",
    "client_modified": "2015-05-12T15:50:38Z",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "link_permissions": {
        "allow_comments": true,
        "allow_download": true,
        "audience_options": [
            {
                "allowed": true,
                "audience": {
                    ".tag": "public"
                }
            },
            {
                "allowed": false,
                "audience": {
                    ".tag": "team"
                }
            },
            {
                "allowed": true,
                "audience": {
                    ".tag": "no_one"
                }
            }
        ],
        "can_allow_download": true,
        "can_disallow_download": false,
        "can_remove_expiry": false,
        "can_remove_password": true,
        "can_revoke": false,
        "can_set_expiry": false,
        "can_set_password": true,
        "can_use_extended_sharing_controls": false,
        "require_password": false,
        "resolved_visibility": {
            ".tag": "public"
        },
        "revoke_failure_reason": {
            ".tag": "owner_only"
        },
        "team_restricts_comments": true,
        "visibility_policies": [
            {
                "allowed": true,
                "policy": {
                    ".tag": "public"
                },
                "resolved_policy": {
                    ".tag": "public"
                }
            },
            {
                "allowed": true,
                "policy": {
                    ".tag": "password"
                },
                "resolved_policy": {
                    ".tag": "password"
                }
            }
        ]
    },
    "name": "Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "size": 7212,
    "team_member_info": {
        "display_name": "Roger Rabbit",
        "member_id": "dbmid:abcd1234",
        "team_info": {
            "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
            "name": "Acme, Inc."
        }
    },
    "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
}
{
    ".tag": "folder",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "link_permissions": {
        "allow_comments": true,
        "allow_download": true,
        "audience_options": [
            {
                "allowed": true,
                "audience": {
                    ".tag": "public"
                }
            },
            {
                "allowed": false,
                "audience": {
                    ".tag": "team"
                }
            },
            {
                "allowed": true,
                "audience": {
                    ".tag": "no_one"
                }
            }
        ],
        "can_allow_download": true,
        "can_disallow_download": false,
        "can_remove_expiry": false,
        "can_remove_password": true,
        "can_revoke": false,
        "can_set_expiry": false,
        "can_set_password": true,
        "can_use_extended_sharing_controls": false,
        "require_password": false,
        "resolved_visibility": {
            ".tag": "public"
        },
        "revoke_failure_reason": {
            ".tag": "owner_only"
        },
        "team_restricts_comments": true,
        "visibility_policies": [
            {
                "allowed": true,
                "policy": {
                    ".tag": "public"
                },
                "resolved_policy": {
                    ".tag": "public"
                }
            },
            {
                "allowed": true,
                "policy": {
                    ".tag": "password"
                },
                "resolved_policy": {
                    ".tag": "password"
                }
            }
        ]
    },
    "name": "Math",
    "path_lower": "/homework/math",
    "team_member_info": {
        "display_name": "Roger Rabbit",
        "member_id": "dbmid:abcd1234",
        "team_info": {
            "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
            "name": "Acme, Inc."
        }
    },
    "url": "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
}
SharedLinkMetadata (datatype with subtypes)
The metadata of a shared link.
file
folder
Errors
Example: shared_link_not_found
{
    "error": {
        ".tag": "shared_link_not_found"
    },
    "error_summary": "shared_link_not_found/..."
}
Example: shared_link_access_denied
{
    "error": {
        ".tag": "shared_link_access_denied"
    },
    "error_summary": "shared_link_access_denied/..."
}
Example: unsupported_link_type
{
    "error": {
        ".tag": "unsupported_link_type"
    },
    "error_summary": "unsupported_link_type/..."
}
Example: unsupported_parameter_field
{
    "error": {
        ".tag": "unsupported_parameter_field"
    },
    "error_summary": "unsupported_parameter_field/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SharedLinkMetadataError (union)
The potential errors for a call to get_shared_link_metadata.
shared_link_not_foundVoidThe shared link wasn't found.
shared_link_access_deniedVoidThe caller is not allowed to access this shared link.
unsupported_link_typeVoidThis type of link is not supported; use files.export instead.
unsupported_parameter_fieldVoidPrivate shared links do not support `path` or `link_password` parameter fields.
See also general errors.

/list_file_members


Description

Use to obtain the members who have been invited to a file, both inherited and uninherited members.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_file_members
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_file_members \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"file\":\"id:3kmLmQFnf1AAAAAAAAAAAw\",\"include_inherited\":true,\"limit\":100}"
Parameters
{
    "file": "id:3kmLmQFnf1AAAAAAAAAAAw",
    "include_inherited": true,
    "limit": 100
}
ListFileMembersArg
Arguments for list_file_members.
fileString(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")The file for which you want to see members.
actionsList of ()?The actions for which to return permissions on a member. This field is optional.
include_inheritedBooleanWhether to include members who only have access from a parent shared folder. The default for this field is True.
limitUInt32(min=1, max=300)Number of members to return max per query. Defaults to 100 if no limit is specified. The default for this field is 100.
Returns
{
    "groups": [
        {
            "access_type": {
                ".tag": "editor"
            },
            "group": {
                "group_id": "g:e2db7665347abcd600000000001a2b3c",
                "group_management_type": {
                    ".tag": "user_managed"
                },
                "group_name": "Test group",
                "group_type": {
                    ".tag": "user_managed"
                },
                "is_member": false,
                "is_owner": false,
                "member_count": 10,
                "same_team": true
            },
            "is_inherited": false,
            "permissions": []
        }
    ],
    "invitees": [
        {
            "access_type": {
                ".tag": "viewer"
            },
            "invitee": {
                ".tag": "email",
                "email": "jessica@example.com"
            },
            "is_inherited": false,
            "permissions": []
        }
    ],
    "users": [
        {
            "access_type": {
                ".tag": "owner"
            },
            "is_inherited": false,
            "permissions": [],
            "platform_type": {
                ".tag": "unknown"
            },
            "time_last_seen": "2016-01-20T00:00:00Z",
            "user": {
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "display_name": "Robert Smith",
                "email": "bob@example.com",
                "same_team": true,
                "team_member_id": "dbmid:abcd1234"
            }
        }
    ]
}
SharedFileMembers
Shared file user, group, and invitee membership. Used for the results of list_file_members and list_file_members/continue, and used as part of the results for list_file_members/batch.
usersList of ()The list of user members of the shared file.
groupsList of ()The list of group members of the shared file.
inviteesList of ()The list of invited members of a file, but have not logged in and claimed this.
cursor String?Present if there are additional shared file members that have not been returned yet. Pass the cursor into list_file_members/continue to list additional members. This field is optional.
Errors
ListFileMembersError (open union)
Error for list_file_members.
user_error
access_error
See also general errors.

/list_file_members/batch


Description

Get members of multiple files at once. The arguments to this route are more limited, and the limit on query result size per file is more strict. To customize the results more, use the individual file endpoint. Inherited users and groups are not included in the result, and permissions are not returned for this endpoint.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_file_members/batch
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_file_members/batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"files\":[\"id:3kmLmQFnf1AAAAAAAAAAAw\",\"id:VvTaJu2VZzAAAAAAAAAADQ\"],\"limit\":1000}"
Parameters
{
    "files": [
        "id:3kmLmQFnf1AAAAAAAAAAAw",
        "id:VvTaJu2VZzAAAAAAAAAADQ"
    ],
    "limit": 1000
}
ListFileMembersBatchArg
Arguments for list_file_members/batch.
files List of (String(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?"), max_items=100)Files for which to return members.
limitUInt32(max=3000)Number of members to return max per query. Defaults to 1000 if no limit is specified. The default for this field is 1000.
Returns
List of (ListFileMembersBatchResult)
Per-file result for list_file_members/batch.
fileString(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")This is the input file identifier, whether an ID or a path.
resultThe result for this particular file.
Errors
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SharingUserError (open union)
User account had a problem preventing this action.
email_unverifiedVoidThis user's email address is not verified. This functionality is only available on accounts with a verified email address. Users can verify their email address here.
See also general errors.

/list_file_members/continue


Description

Once a cursor has been retrieved from list_file_members or list_file_members/batch, use this to paginate through all shared file members.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_file_members/continue
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_file_members/continue \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
ListFileMembersContinueArg
Arguments for list_file_members/continue.
cursorStringThe cursor returned by your last call to list_file_members, list_file_members/continue, or list_file_members/batch.
Returns
{
    "groups": [
        {
            "access_type": {
                ".tag": "editor"
            },
            "group": {
                "group_id": "g:e2db7665347abcd600000000001a2b3c",
                "group_management_type": {
                    ".tag": "user_managed"
                },
                "group_name": "Test group",
                "group_type": {
                    ".tag": "user_managed"
                },
                "is_member": false,
                "is_owner": false,
                "member_count": 10,
                "same_team": true
            },
            "is_inherited": false,
            "permissions": []
        }
    ],
    "invitees": [
        {
            "access_type": {
                ".tag": "viewer"
            },
            "invitee": {
                ".tag": "email",
                "email": "jessica@example.com"
            },
            "is_inherited": false,
            "permissions": []
        }
    ],
    "users": [
        {
            "access_type": {
                ".tag": "owner"
            },
            "is_inherited": false,
            "permissions": [],
            "platform_type": {
                ".tag": "unknown"
            },
            "time_last_seen": "2016-01-20T00:00:00Z",
            "user": {
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "display_name": "Robert Smith",
                "email": "bob@example.com",
                "same_team": true,
                "team_member_id": "dbmid:abcd1234"
            }
        }
    ]
}
SharedFileMembers
Shared file user, group, and invitee membership. Used for the results of list_file_members and list_file_members/continue, and used as part of the results for list_file_members/batch.
usersList of ()The list of user members of the shared file.
groupsList of ()The list of group members of the shared file.
inviteesList of ()The list of invited members of a file, but have not logged in and claimed this.
cursor String?Present if there are additional shared file members that have not been returned yet. Pass the cursor into list_file_members/continue to list additional members. This field is optional.
Errors
Example: invalid_cursor
{
    "error": {
        ".tag": "invalid_cursor"
    },
    "error_summary": "invalid_cursor/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ListFileMembersContinueError (open union)
Error for list_file_members/continue.
user_error
access_error
invalid_cursorVoidListFileMembersContinueArg.cursor is invalid.
See also general errors.

/list_folder_members


Description

Returns shared folder membership by its folder ID.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_folder_members
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_folder_members \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"actions\":[],\"limit\":10,\"shared_folder_id\":\"84528192421\"}"
Parameters
{
    "actions": [],
    "limit": 10,
    "shared_folder_id": "84528192421"
}
ListFolderMembersArgs
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
actionsList of ()?This is a list indicating whether each returned member will include a boolean value MemberPermission.allow that describes whether the current user can perform the MemberAction on the member. This field is optional.
limitUInt32(min=1, max=1000)The maximum number of results that include members, groups and invitees to return per request. The default for this field is 1000.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "groups": [
        {
            "access_type": {
                ".tag": "editor"
            },
            "group": {
                "group_id": "g:e2db7665347abcd600000000001a2b3c",
                "group_management_type": {
                    ".tag": "user_managed"
                },
                "group_name": "Test group",
                "group_type": {
                    ".tag": "user_managed"
                },
                "is_member": false,
                "is_owner": false,
                "member_count": 10,
                "same_team": true
            },
            "is_inherited": false,
            "permissions": []
        }
    ],
    "invitees": [
        {
            "access_type": {
                ".tag": "viewer"
            },
            "invitee": {
                ".tag": "email",
                "email": "jessica@example.com"
            },
            "is_inherited": false,
            "permissions": []
        }
    ],
    "users": [
        {
            "access_type": {
                ".tag": "owner"
            },
            "is_inherited": false,
            "permissions": [],
            "user": {
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "display_name": "Robert Smith",
                "email": "bob@example.com",
                "same_team": true,
                "team_member_id": "dbmid:abcd1234"
            }
        }
    ]
}
SharedFolderMembers
Shared folder user and group membership.
usersList of ()The list of user members of the shared folder.
groupsList of ()The list of group members of the shared folder.
inviteesList of ()The list of invitees to the shared folder.
cursor String?Present if there are additional shared folder members that have not been returned yet. Pass the cursor into list_folder_members/continue to list additional members. This field is optional.
Errors
Example: invalid_id
{
    "error": {
        ".tag": "invalid_id"
    },
    "error_summary": "invalid_id/..."
}
Example: not_a_member
{
    "error": {
        ".tag": "not_a_member"
    },
    "error_summary": "not_a_member/..."
}
Example: invalid_member
{
    "error": {
        ".tag": "invalid_member"
    },
    "error_summary": "invalid_member/..."
}
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: unmounted
{
    "error": {
        ".tag": "unmounted"
    },
    "error_summary": "unmounted/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SharedFolderAccessError (open union)
There is an error accessing the shared folder.
invalid_idVoidThis shared folder ID is invalid.
not_a_memberVoidThe user is not a member of the shared folder thus cannot access it.
invalid_memberVoidThe user does not exist or their account is disabled.
email_unverifieddeprecatedVoidField is deprecated. Never set.
unmountedVoidThe shared folder is unmounted.
See also general errors.

/list_folder_members/continue


Description

Once a cursor has been retrieved from list_folder_members, use this to paginate through all shared folder members.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_folder_members/continue
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_folder_members/continue \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
ListFolderMembersContinueArg
cursorStringThe cursor returned by your last call to list_folder_members or list_folder_members/continue.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "groups": [
        {
            "access_type": {
                ".tag": "editor"
            },
            "group": {
                "group_id": "g:e2db7665347abcd600000000001a2b3c",
                "group_management_type": {
                    ".tag": "user_managed"
                },
                "group_name": "Test group",
                "group_type": {
                    ".tag": "user_managed"
                },
                "is_member": false,
                "is_owner": false,
                "member_count": 10,
                "same_team": true
            },
            "is_inherited": false,
            "permissions": []
        }
    ],
    "invitees": [
        {
            "access_type": {
                ".tag": "viewer"
            },
            "invitee": {
                ".tag": "email",
                "email": "jessica@example.com"
            },
            "is_inherited": false,
            "permissions": []
        }
    ],
    "users": [
        {
            "access_type": {
                ".tag": "owner"
            },
            "is_inherited": false,
            "permissions": [],
            "user": {
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "display_name": "Robert Smith",
                "email": "bob@example.com",
                "same_team": true,
                "team_member_id": "dbmid:abcd1234"
            }
        }
    ]
}
SharedFolderMembers
Shared folder user and group membership.
usersList of ()The list of user members of the shared folder.
groupsList of ()The list of group members of the shared folder.
inviteesList of ()The list of invitees to the shared folder.
cursor String?Present if there are additional shared folder members that have not been returned yet. Pass the cursor into list_folder_members/continue to list additional members. This field is optional.
Errors
Example: invalid_cursor
{
    "error": {
        ".tag": "invalid_cursor"
    },
    "error_summary": "invalid_cursor/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ListFolderMembersContinueError (open union)
access_error
invalid_cursorVoidListFolderMembersContinueArg.cursor is invalid.
See also general errors.

/list_folders


Description

Return the list of all shared folders the current user has access to.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_folders
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_folders \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"actions\":[],\"limit\":100}"
Parameters
{
    "actions": [],
    "limit": 100
}
ListFoldersArgs
limitUInt32(min=1, max=1000)The maximum number of results to return per request. The default for this field is 1000.
actionsList of ()?A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the response's SharedFolderMetadata.permissions field describing the actions the authenticated user can perform on the folder. This field is optional.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "entries": [
        {
            "access_inheritance": {
                ".tag": "inherit"
            },
            "access_type": {
                ".tag": "owner"
            },
            "folder_id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "is_inside_team_folder": false,
            "is_team_folder": false,
            "link_metadata": {
                "audience_options": [
                    {
                        ".tag": "public"
                    },
                    {
                        ".tag": "team"
                    },
                    {
                        ".tag": "members"
                    }
                ],
                "current_audience": {
                    ".tag": "public"
                },
                "link_permissions": [
                    {
                        "action": {
                            ".tag": "change_audience"
                        },
                        "allow": true
                    }
                ],
                "password_protected": false,
                "url": ""
            },
            "name": "dir",
            "path_lower": "/dir",
            "permissions": [],
            "policy": {
                "acl_update_policy": {
                    ".tag": "owner"
                },
                "member_policy": {
                    ".tag": "anyone"
                },
                "resolved_member_policy": {
                    ".tag": "team"
                },
                "shared_link_policy": {
                    ".tag": "anyone"
                }
            },
            "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
            "shared_folder_id": "84528192421",
            "time_invited": "2016-01-20T00:00:00Z"
        }
    ]
}
ListFoldersResult
Result for list_folders or list_mountable_folders, depending on which endpoint was requested. Unmounted shared folders can be identified by the absence of SharedFolderMetadata.path_lower.
entriesList of ()List of all shared folders the authenticated user has access to.
cursor String?Present if there are additional shared folders that have not been returned yet. Pass the cursor into the corresponding continue endpoint (either list_folders/continue or list_mountable_folders/continue) to list additional folders. This field is optional.
Errors
No endpoint-specific errors.
See also general errors.

/list_folders/continue


Description

Once a cursor has been retrieved from list_folders, use this to paginate through all shared folders. The cursor must come from a previous call to list_folders or list_folders/continue.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_folders/continue
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_folders/continue \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
ListFoldersContinueArg
cursorStringThe cursor returned by the previous API call specified in the endpoint description.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "entries": [
        {
            "access_inheritance": {
                ".tag": "inherit"
            },
            "access_type": {
                ".tag": "owner"
            },
            "folder_id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "is_inside_team_folder": false,
            "is_team_folder": false,
            "link_metadata": {
                "audience_options": [
                    {
                        ".tag": "public"
                    },
                    {
                        ".tag": "team"
                    },
                    {
                        ".tag": "members"
                    }
                ],
                "current_audience": {
                    ".tag": "public"
                },
                "link_permissions": [
                    {
                        "action": {
                            ".tag": "change_audience"
                        },
                        "allow": true
                    }
                ],
                "password_protected": false,
                "url": ""
            },
            "name": "dir",
            "path_lower": "/dir",
            "permissions": [],
            "policy": {
                "acl_update_policy": {
                    ".tag": "owner"
                },
                "member_policy": {
                    ".tag": "anyone"
                },
                "resolved_member_policy": {
                    ".tag": "team"
                },
                "shared_link_policy": {
                    ".tag": "anyone"
                }
            },
            "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
            "shared_folder_id": "84528192421",
            "time_invited": "2016-01-20T00:00:00Z"
        }
    ]
}
ListFoldersResult
Result for list_folders or list_mountable_folders, depending on which endpoint was requested. Unmounted shared folders can be identified by the absence of SharedFolderMetadata.path_lower.
entriesList of ()List of all shared folders the authenticated user has access to.
cursor String?Present if there are additional shared folders that have not been returned yet. Pass the cursor into the corresponding continue endpoint (either list_folders/continue or list_mountable_folders/continue) to list additional folders. This field is optional.
Errors
Example: invalid_cursor
{
    "error": {
        ".tag": "invalid_cursor"
    },
    "error_summary": "invalid_cursor/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ListFoldersContinueError (open union)
invalid_cursorVoidListFoldersContinueArg.cursor is invalid.
See also general errors.

/list_mountable_folders


Description

Return the list of all shared folders the current user can mount or unmount.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_mountable_folders
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_mountable_folders \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"actions\":[],\"limit\":100}"
Parameters
{
    "actions": [],
    "limit": 100
}
ListFoldersArgs
limitUInt32(min=1, max=1000)The maximum number of results to return per request. The default for this field is 1000.
actionsList of ()?A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the response's SharedFolderMetadata.permissions field describing the actions the authenticated user can perform on the folder. This field is optional.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "entries": [
        {
            "access_inheritance": {
                ".tag": "inherit"
            },
            "access_type": {
                ".tag": "owner"
            },
            "folder_id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "is_inside_team_folder": false,
            "is_team_folder": false,
            "link_metadata": {
                "audience_options": [
                    {
                        ".tag": "public"
                    },
                    {
                        ".tag": "team"
                    },
                    {
                        ".tag": "members"
                    }
                ],
                "current_audience": {
                    ".tag": "public"
                },
                "link_permissions": [
                    {
                        "action": {
                            ".tag": "change_audience"
                        },
                        "allow": true
                    }
                ],
                "password_protected": false,
                "url": ""
            },
            "name": "dir",
            "path_lower": "/dir",
            "permissions": [],
            "policy": {
                "acl_update_policy": {
                    ".tag": "owner"
                },
                "member_policy": {
                    ".tag": "anyone"
                },
                "resolved_member_policy": {
                    ".tag": "team"
                },
                "shared_link_policy": {
                    ".tag": "anyone"
                }
            },
            "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
            "shared_folder_id": "84528192421",
            "time_invited": "2016-01-20T00:00:00Z"
        }
    ]
}
ListFoldersResult
Result for list_folders or list_mountable_folders, depending on which endpoint was requested. Unmounted shared folders can be identified by the absence of SharedFolderMetadata.path_lower.
entriesList of ()List of all shared folders the authenticated user has access to.
cursor String?Present if there are additional shared folders that have not been returned yet. Pass the cursor into the corresponding continue endpoint (either list_folders/continue or list_mountable_folders/continue) to list additional folders. This field is optional.
Errors
No endpoint-specific errors.
See also general errors.

/list_mountable_folders/continue


Description

Once a cursor has been retrieved from list_mountable_folders, use this to paginate through all mountable shared folders. The cursor must come from a previous call to list_mountable_folders or list_mountable_folders/continue.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_mountable_folders/continue
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_mountable_folders/continue \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
ListFoldersContinueArg
cursorStringThe cursor returned by the previous API call specified in the endpoint description.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "entries": [
        {
            "access_inheritance": {
                ".tag": "inherit"
            },
            "access_type": {
                ".tag": "owner"
            },
            "folder_id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "is_inside_team_folder": false,
            "is_team_folder": false,
            "link_metadata": {
                "audience_options": [
                    {
                        ".tag": "public"
                    },
                    {
                        ".tag": "team"
                    },
                    {
                        ".tag": "members"
                    }
                ],
                "current_audience": {
                    ".tag": "public"
                },
                "link_permissions": [
                    {
                        "action": {
                            ".tag": "change_audience"
                        },
                        "allow": true
                    }
                ],
                "password_protected": false,
                "url": ""
            },
            "name": "dir",
            "path_lower": "/dir",
            "permissions": [],
            "policy": {
                "acl_update_policy": {
                    ".tag": "owner"
                },
                "member_policy": {
                    ".tag": "anyone"
                },
                "resolved_member_policy": {
                    ".tag": "team"
                },
                "shared_link_policy": {
                    ".tag": "anyone"
                }
            },
            "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
            "shared_folder_id": "84528192421",
            "time_invited": "2016-01-20T00:00:00Z"
        }
    ]
}
ListFoldersResult
Result for list_folders or list_mountable_folders, depending on which endpoint was requested. Unmounted shared folders can be identified by the absence of SharedFolderMetadata.path_lower.
entriesList of ()List of all shared folders the authenticated user has access to.
cursor String?Present if there are additional shared folders that have not been returned yet. Pass the cursor into the corresponding continue endpoint (either list_folders/continue or list_mountable_folders/continue) to list additional folders. This field is optional.
Errors
Example: invalid_cursor
{
    "error": {
        ".tag": "invalid_cursor"
    },
    "error_summary": "invalid_cursor/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ListFoldersContinueError (open union)
invalid_cursorVoidListFoldersContinueArg.cursor is invalid.
See also general errors.

/list_received_files


Description

Returns a list of all files shared with current user. Does not include files the user has received via shared folders, and does not include unclaimed invitations.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_received_files
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_received_files \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"actions\":[],\"limit\":100}"
Parameters
{
    "actions": [],
    "limit": 100
}
ListFilesArg
Arguments for list_received_files.
limitUInt32(min=1, max=300)Number of files to return max per query. Defaults to 100 if no limit is specified. The default for this field is 100.
actionsList of ()?A list of `FileAction`s corresponding to `FilePermission`s that should appear in the response's SharedFileMetadata.permissions field describing the actions the authenticated user can perform on the file. This field is optional.
Returns
{
    "cursor": "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9cmV2aXNpb24H3Qf6o1fkHxQ",
    "entries": [
        {
            "access_type": {
                ".tag": "viewer"
            },
            "id": "id:3kmLmQFnf1AAAAAAAAAAAw",
            "name": "file.txt",
            "owner_display_names": [
                "Jane Doe"
            ],
            "owner_team": {
                "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
                "name": "Acme, Inc."
            },
            "path_display": "/dir/file.txt",
            "path_lower": "/dir/file.txt",
            "permissions": [],
            "policy": {
                "acl_update_policy": {
                    ".tag": "owner"
                },
                "member_policy": {
                    ".tag": "anyone"
                },
                "resolved_member_policy": {
                    ".tag": "team"
                },
                "shared_link_policy": {
                    ".tag": "anyone"
                }
            },
            "preview_url": "https://www.dropbox.com/scl/fi/fir9vjelf",
            "time_invited": "2016-01-20T00:00:00Z"
        }
    ]
}
ListFilesResult
Success results for list_received_files.
entriesList of ()Information about the files shared with current user.
cursor String?Cursor used to obtain additional shared files. This field is optional.
Errors
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SharingUserError (open union)
User account had a problem preventing this action.
email_unverifiedVoidThis user's email address is not verified. This functionality is only available on accounts with a verified email address. Users can verify their email address here.
See also general errors.

/list_received_files/continue


Description

Get more results with a cursor from list_received_files.

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

URL Structure
https://api.dropboxapi.com/2/sharing/list_received_files/continue
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_received_files/continue \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9emfGRlc2MCRWxpbWl0BGRId\"}"
Parameters
{
    "cursor": "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9emfGRlc2MCRWxpbWl0BGRId"
}
ListFilesContinueArg
Arguments for list_received_files/continue.
cursorStringCursor in ListFilesResult.cursor.
Returns
{
    "cursor": "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9cmV2aXNpb24H3Qf6o1fkHxQ",
    "entries": [
        {
            "access_type": {
                ".tag": "viewer"
            },
            "id": "id:3kmLmQFnf1AAAAAAAAAAAw",
            "name": "file.txt",
            "owner_display_names": [
                "Jane Doe"
            ],
            "owner_team": {
                "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
                "name": "Acme, Inc."
            },
            "path_display": "/dir/file.txt",
            "path_lower": "/dir/file.txt",
            "permissions": [],
            "policy": {
                "acl_update_policy": {
                    ".tag": "owner"
                },
                "member_policy": {
                    ".tag": "anyone"
                },
                "resolved_member_policy": {
                    ".tag": "team"
                },
                "shared_link_policy": {
                    ".tag": "anyone"
                }
            },
            "preview_url": "https://www.dropbox.com/scl/fi/fir9vjelf",
            "time_invited": "2016-01-20T00:00:00Z"
        }
    ]
}
ListFilesResult
Success results for list_received_files.
entriesList of ()Information about the files shared with current user.
cursor String?Cursor used to obtain additional shared files. This field is optional.
Errors
Example: invalid_cursor
{
    "error": {
        ".tag": "invalid_cursor"
    },
    "error_summary": "invalid_cursor/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ListFilesContinueError (open union)
Error results for list_received_files/continue.
user_errorUser account had a problem.
invalid_cursorVoidListFilesContinueArg.cursor is invalid.
See also general errors.

/list_shared_links


Description

List shared links of this user. If no path is given, returns a list of all shared links for the current user. For members of business teams using team space and member folders, returns all shared links in the team member's home folder unless the team space ID is specified in the request header. For more information, refer to the Namespace Guide. If a non-empty path is given, returns a list of all shared links that allow access to the given path - direct links to the given path and links to parent folders of the given path. Links to parent folders can be suppressed by setting direct_only to true. If using an admin escalated auth, you must provide a path as well as setting direct_only to true.

URL Structure
https://api.dropboxapi.com/2/sharing/list_shared_links
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/list_shared_links \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
Example: List all links.
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
Example: path
{
    "path": "/Homework/Math"
}
Example: id
{
    "path": "id:a4ayc_80_OEAAAAAAAAAYa"
}
Example: rev
{
    "path": "rev:a1c10ce0dd78"
}
Example: id_no_parent_links
{
    "direct_only": true,
    "path": "id:a4ayc_80_OEAAAAAAAAAYa"
}
ListSharedLinksArg
path String(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")?See list_shared_links description. This field is optional.
cursor String?The cursor returned by your last call to list_shared_links. This field is optional.
direct_only Boolean?See list_shared_links description. This field is optional.
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "has_more": true,
    "links": [
        {
            ".tag": "file",
            "client_modified": "2015-05-12T15:50:38Z",
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "link_permissions": {
                "allow_comments": true,
                "allow_download": true,
                "audience_options": [
                    {
                        "allowed": true,
                        "audience": {
                            ".tag": "public"
                        }
                    },
                    {
                        "allowed": false,
                        "audience": {
                            ".tag": "team"
                        }
                    },
                    {
                        "allowed": true,
                        "audience": {
                            ".tag": "no_one"
                        }
                    }
                ],
                "can_allow_download": true,
                "can_disallow_download": false,
                "can_remove_expiry": false,
                "can_remove_password": true,
                "can_revoke": false,
                "can_set_expiry": false,
                "can_set_password": true,
                "can_use_extended_sharing_controls": false,
                "require_password": false,
                "resolved_visibility": {
                    ".tag": "public"
                },
                "revoke_failure_reason": {
                    ".tag": "owner_only"
                },
                "team_restricts_comments": true,
                "visibility_policies": [
                    {
                        "allowed": true,
                        "policy": {
                            ".tag": "public"
                        },
                        "resolved_policy": {
                            ".tag": "public"
                        }
                    },
                    {
                        "allowed": true,
                        "policy": {
                            ".tag": "password"
                        },
                        "resolved_policy": {
                            ".tag": "password"
                        }
                    }
                ]
            },
            "name": "Prime_Numbers.txt",
            "path_lower": "/homework/math/prime_numbers.txt",
            "rev": "a1c10ce0dd78",
            "server_modified": "2015-05-12T15:50:38Z",
            "size": 7212,
            "team_member_info": {
                "display_name": "Roger Rabbit",
                "member_id": "dbmid:abcd1234",
                "team_info": {
                    "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
                    "name": "Acme, Inc."
                }
            },
            "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
        }
    ]
}
ListSharedLinksResult
linksList of ()Shared links applicable to the path argument.
has_moreBooleanIs true if there are additional shared links that have not been returned yet. Pass the cursor into list_shared_links to retrieve them.
cursor String?Pass the cursor into list_shared_links to obtain the additional links. Cursor is returned only if no path is given. This field is optional.
Errors
Example: reset
{
    "error": {
        ".tag": "reset"
    },
    "error_summary": "reset/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
ListSharedLinksError (open union)
path
resetVoidIndicates that the cursor has been invalidated. Call list_shared_links to obtain a new cursor.
See also general errors.

/modify_shared_link_settings


Description

Modify the shared link's settings. If the requested visibility conflict with the shared links policy of the team or the shared folder (in case the linked file is part of a shared folder) then the LinkPermissions.resolved_visibility of the returned SharedLinkMetadata will reflect the actual visibility of the shared link and the LinkPermissions.requested_visibility will reflect the requested visibility.

URL Structure
https://api.dropboxapi.com/2/sharing/modify_shared_link_settings
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/modify_shared_link_settings \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"remove_expiration\":false,\"settings\":{\"access\":\"viewer\",\"allow_download\":true,\"audience\":\"public\",\"requested_visibility\":\"public\"},\"url\":\"https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0\"}"
Parameters
{
    "remove_expiration": false,
    "settings": {
        "access": "viewer",
        "allow_download": true,
        "audience": "public",
        "requested_visibility": "public"
    },
    "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
}
ModifySharedLinkSettingsArgs
urlStringURL of the shared link to change its settings.
settingsSet of settings for the shared link.
remove_expirationBooleanIf set to true, removes the expiration of the shared link. The default for this field is False.
Returns
{
    ".tag": "file",
    "client_modified": "2015-05-12T15:50:38Z",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "link_permissions": {
        "allow_comments": true,
        "allow_download": true,
        "audience_options": [
            {
                "allowed": true,
                "audience": {
                    ".tag": "public"
                }
            },
            {
                "allowed": false,
                "audience": {
                    ".tag": "team"
                }
            },
            {
                "allowed": true,
                "audience": {
                    ".tag": "no_one"
                }
            }
        ],
        "can_allow_download": true,
        "can_disallow_download": false,
        "can_remove_expiry": false,
        "can_remove_password": true,
        "can_revoke": false,
        "can_set_expiry": false,
        "can_set_password": true,
        "can_use_extended_sharing_controls": false,
        "require_password": false,
        "resolved_visibility": {
            ".tag": "public"
        },
        "revoke_failure_reason": {
            ".tag": "owner_only"
        },
        "team_restricts_comments": true,
        "visibility_policies": [
            {
                "allowed": true,
                "policy": {
                    ".tag": "public"
                },
                "resolved_policy": {
                    ".tag": "public"
                }
            },
            {
                "allowed": true,
                "policy": {
                    ".tag": "password"
                },
                "resolved_policy": {
                    ".tag": "password"
                }
            }
        ]
    },
    "name": "Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "size": 7212,
    "team_member_info": {
        "display_name": "Roger Rabbit",
        "member_id": "dbmid:abcd1234",
        "team_info": {
            "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
            "name": "Acme, Inc."
        }
    },
    "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
}
{
    ".tag": "folder",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "link_permissions": {
        "allow_comments": true,
        "allow_download": true,
        "audience_options": [
            {
                "allowed": true,
                "audience": {
                    ".tag": "public"
                }
            },
            {
                "allowed": false,
                "audience": {
                    ".tag": "team"
                }
            },
            {
                "allowed": true,
                "audience": {
                    ".tag": "no_one"
                }
            }
        ],
        "can_allow_download": true,
        "can_disallow_download": false,
        "can_remove_expiry": false,
        "can_remove_password": true,
        "can_revoke": false,
        "can_set_expiry": false,
        "can_set_password": true,
        "can_use_extended_sharing_controls": false,
        "require_password": false,
        "resolved_visibility": {
            ".tag": "public"
        },
        "revoke_failure_reason": {
            ".tag": "owner_only"
        },
        "team_restricts_comments": true,
        "visibility_policies": [
            {
                "allowed": true,
                "policy": {
                    ".tag": "public"
                },
                "resolved_policy": {
                    ".tag": "public"
                }
            },
            {
                "allowed": true,
                "policy": {
                    ".tag": "password"
                },
                "resolved_policy": {
                    ".tag": "password"
                }
            }
        ]
    },
    "name": "Math",
    "path_lower": "/homework/math",
    "team_member_info": {
        "display_name": "Roger Rabbit",
        "member_id": "dbmid:abcd1234",
        "team_info": {
            "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
            "name": "Acme, Inc."
        }
    },
    "url": "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
}
SharedLinkMetadata (datatype with subtypes)
The metadata of a shared link.
file
folder
Errors
Example: shared_link_not_found
{
    "error": {
        ".tag": "shared_link_not_found"
    },
    "error_summary": "shared_link_not_found/..."
}
Example: shared_link_access_denied
{
    "error": {
        ".tag": "shared_link_access_denied"
    },
    "error_summary": "shared_link_access_denied/..."
}
Example: unsupported_link_type
{
    "error": {
        ".tag": "unsupported_link_type"
    },
    "error_summary": "unsupported_link_type/..."
}
Example: unsupported_parameter_field
{
    "error": {
        ".tag": "unsupported_parameter_field"
    },
    "error_summary": "unsupported_parameter_field/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: email_not_verified
{
    "error": {
        ".tag": "email_not_verified"
    },
    "error_summary": "email_not_verified/..."
}
ModifySharedLinkSettingsError (union)
shared_link_not_foundVoidThe shared link wasn't found.
shared_link_access_deniedVoidThe caller is not allowed to access this shared link.
unsupported_link_typeVoidThis type of link is not supported; use files.export instead.
unsupported_parameter_fieldVoidPrivate shared links do not support `path` or `link_password` parameter fields.
settings_errorThere is an error with the given settings.
email_not_verifiedVoidThis user's email address is not verified. This functionality is only available on accounts with a verified email address. Users can verify their email address here.
See also general errors.

/mount_folder


Description

The current user mounts the designated folder. Mount a shared folder for a user after they have been added as a member. Once mounted, the shared folder will appear in their Dropbox.

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

URL Structure
https://api.dropboxapi.com/2/sharing/mount_folder
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/mount_folder \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"shared_folder_id\":\"84528192421\"}"
Parameters
{
    "shared_folder_id": "84528192421"
}
MountFolderArg
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID of the shared folder to mount.
Returns
{
    "access_inheritance": {
        ".tag": "inherit"
    },
    "access_type": {
        ".tag": "owner"
    },
    "folder_id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_inside_team_folder": false,
    "is_team_folder": false,
    "link_metadata": {
        "audience_options": [
            {
                ".tag": "public"
            },
            {
                ".tag": "team"
            },
            {
                ".tag": "members"
            }
        ],
        "current_audience": {
            ".tag": "public"
        },
        "link_permissions": [
            {
                "action": {
                    ".tag": "change_audience"
                },
                "allow": true
            }
        ],
        "password_protected": false,
        "url": ""
    },
    "name": "dir",
    "path_lower": "/dir",
    "permissions": [],
    "policy": {
        "acl_update_policy": {
            ".tag": "owner"
        },
        "member_policy": {
            ".tag": "anyone"
        },
        "resolved_member_policy": {
            ".tag": "team"
        },
        "shared_link_policy": {
            ".tag": "anyone"
        }
    },
    "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
    "shared_folder_id": "84528192421",
    "time_invited": "2016-01-20T00:00:00Z"
}
SharedFolderMetadata
The metadata which includes basic information about the shared folder.
access_typeThe current user's access level for this shared folder.
is_inside_team_folderBooleanWhether this folder is inside of a team folder.
is_team_folderBooleanWhether this folder is a team folder.
nameStringThe name of the this shared folder.
policyPolicies governing this shared folder.
preview_urlStringURL for displaying a web preview of the shared folder.
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID of the shared folder.
time_invitedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")Timestamp indicating when the current user was invited to this shared folder.
owner_display_names List of (String)?The display names of the users that own the folder. If the folder is part of a team folder, the display names of the team admins are also included. Absent if the owner display names cannot be fetched. This field is optional.
owner_team?The team that owns the folder. This field is not present if the folder is not owned by a team. This field is optional.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")?The ID of the parent shared folder. This field is present only if the folder is contained within another shared folder. This field is optional.
path_display String?The full path of this shared folder. Absent for unmounted folders. This field is optional.
path_lower String?The lower-cased full path of this shared folder. Absent for unmounted folders. This field is optional.
parent_folder_name String?Display name for the parent folder. This field is optional.
link_metadata?The metadata of the shared content link to this shared folder. Absent if there is no link on the folder. This is for an unreleased feature so it may not be returned yet. This field is optional.
permissionsList of ()?Actions the current user may perform on the folder and its contents. The set of permissions corresponds to the FolderActions in the request. This field is optional.
access_inheritanceWhether the folder inherits its members from its parent. The default for this union is inherit.
folder_id String(min_length=4, pattern="id:.+")?The ID of the content. This field is optional.
Errors
Example: inside_shared_folder
{
    "error": {
        ".tag": "inside_shared_folder"
    },
    "error_summary": "inside_shared_folder/..."
}
Example: already_mounted
{
    "error": {
        ".tag": "already_mounted"
    },
    "error_summary": "already_mounted/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: not_mountable
{
    "error": {
        ".tag": "not_mountable"
    },
    "error_summary": "not_mountable/..."
}
Example: must_automount
{
    "error": {
        ".tag": "must_automount"
    },
    "error_summary": "must_automount/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
MountFolderError (open union)
access_error
inside_shared_folderVoidMounting would cause a shared folder to be inside another, which is disallowed.
insufficient_quotaThe current user does not have enough space to mount the shared folder.
already_mountedVoidThe shared folder is already mounted.
no_permissionVoidThe current user does not have permission to perform this action.
not_mountableVoidThe shared folder is not mountable. One example where this can occur is when the shared folder belongs within a team folder in the user's Dropbox.
must_automountVoidThe shared folder is not mountable by directly call APIs, instead the automounter is responsible for mounting it.
See also general errors.

/relinquish_file_membership


Description

The current user relinquishes their membership in the designated file. Note that the current user may still have inherited access to this file through the parent folder.

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

URL Structure
https://api.dropboxapi.com/2/sharing/relinquish_file_membership
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/relinquish_file_membership \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"file\":\"id:3kmLmQFnf1AAAAAAAAAAAw\"}"
Parameters
{
    "file": "id:3kmLmQFnf1AAAAAAAAAAAw"
}
RelinquishFileMembershipArg
fileString(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")The path or id for the file.
Returns
No return values.
Errors
Example: group_access
{
    "error": {
        ".tag": "group_access"
    },
    "error_summary": "group_access/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
RelinquishFileMembershipError (open union)
access_error
group_accessVoidThe current user has access to the shared file via a group. You can't relinquish membership to a file shared via groups.
no_permissionVoidThe current user does not have permission to perform this action.
See also general errors.

/relinquish_folder_membership


Description

The current user relinquishes their membership in the designated shared folder and will no longer have access to the folder. A folder owner cannot relinquish membership in their own folder. This will run synchronously if leave_a_copy is false, and asynchronously if leave_a_copy is true.

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

URL Structure
https://api.dropboxapi.com/2/sharing/relinquish_folder_membership
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/relinquish_folder_membership \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"leave_a_copy\":false,\"shared_folder_id\":\"84528192421\"}"
Parameters
{
    "leave_a_copy": false,
    "shared_folder_id": "84528192421"
}
RelinquishFolderMembershipArg
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
leave_a_copyBooleanKeep a copy of the folder's contents upon relinquishing membership. This must be set to false when the folder is within a team folder or another shared folder. The default for this field is False.
Returns
Example: complete
{
    ".tag": "complete"
}
Example: async_job_id
{
    ".tag": "async_job_id",
    "async_job_id": "34g93hh34h04y384084"
}
LaunchEmptyResult (union)
Result returned by methods that may either launch an asynchronous job or complete synchronously. Upon synchronous completion of the job, no additional information is returned. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
completeVoidThe job finished synchronously and successfully.
Errors
Example: folder_owner
{
    "error": {
        ".tag": "folder_owner"
    },
    "error_summary": "folder_owner/..."
}
Example: mounted
{
    "error": {
        ".tag": "mounted"
    },
    "error_summary": "mounted/..."
}
Example: group_access
{
    "error": {
        ".tag": "group_access"
    },
    "error_summary": "group_access/..."
}
Example: team_folder
{
    "error": {
        ".tag": "team_folder"
    },
    "error_summary": "team_folder/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: no_explicit_access
{
    "error": {
        ".tag": "no_explicit_access"
    },
    "error_summary": "no_explicit_access/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
RelinquishFolderMembershipError (open union)
access_error
folder_ownerVoidThe current user is the owner of the shared folder. Owners cannot relinquish membership to their own folders. Try unsharing or transferring ownership first.
mountedVoidThe shared folder is currently mounted. Unmount the shared folder before relinquishing membership.
group_accessVoidThe current user has access to the shared folder via a group. You can't relinquish membership to folders shared via groups.
team_folderVoidThis action cannot be performed on a team shared folder.
no_permissionVoidThe current user does not have permission to perform this action.
no_explicit_accessVoidThe current user only has inherited access to the shared folder. You can't relinquish inherited membership to folders.
See also general errors.

/remove_file_member_2


Description

Removes a specified member from the file.

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

URL Structure
https://api.dropboxapi.com/2/sharing/remove_file_member_2
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/remove_file_member_2 \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"file\":\"id:3kmLmQFnf1AAAAAAAAAAAw\",\"member\":{\".tag\":\"email\",\"email\":\"justin@example.com\"}}"
Parameters
{
    "file": "id:3kmLmQFnf1AAAAAAAAAAAw",
    "member": {
        ".tag": "email",
        "email": "justin@example.com"
    }
}
RemoveFileMemberArg
Arguments for remove_file_member_2.
fileString(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")File from which to remove members.
memberMember to remove from this file. Note that even if an email is specified, it may result in the removal of a user (not an invitee) if the user's main account corresponds to that email address.
Returns
FileMemberRemoveActionResult (open union)
successMember was successfully removed from this file.
member_errorUser was not able to remove this member.
Errors
RemoveFileMemberError (open union)
Errors for remove_file_member_2.
user_error
access_error
no_explicit_accessThis member does not have explicit access to the file and therefore cannot be removed. The return value is the access that a user might have to the file from a parent folder.
See also general errors.

/remove_folder_member


Description

Allows an owner or editor (if the ACL update policy allows) of a shared folder to remove another member.

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

URL Structure
https://api.dropboxapi.com/2/sharing/remove_folder_member
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/remove_folder_member \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"leave_a_copy\":false,\"member\":{\".tag\":\"email\",\"email\":\"justin@example.com\"},\"shared_folder_id\":\"84528192421\"}"
Parameters
{
    "leave_a_copy": false,
    "member": {
        ".tag": "email",
        "email": "justin@example.com"
    },
    "shared_folder_id": "84528192421"
}
RemoveFolderMemberArg
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
memberThe member to remove from the folder.
leave_a_copyBooleanIf true, the removed user will keep their copy of the folder after it's unshared, assuming it was mounted. Otherwise, it will be removed from their Dropbox. This must be set to false when removing a group, or when the folder is within a team folder or another shared folder.
Returns
{
    ".tag": "async_job_id",
    "async_job_id": "34g93hh34h04y384084"
}
LaunchResultBase (union)
Result returned by methods that launch an asynchronous job. A method who may either launch an asynchronous job, or complete the request synchronously, can use this union by extending it, and adding a 'complete' field with the type of the synchronous response. See LaunchEmptyResult for an example. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
Errors
Example: folder_owner
{
    "error": {
        ".tag": "folder_owner"
    },
    "error_summary": "folder_owner/..."
}
Example: group_access
{
    "error": {
        ".tag": "group_access"
    },
    "error_summary": "group_access/..."
}
Example: team_folder
{
    "error": {
        ".tag": "team_folder"
    },
    "error_summary": "team_folder/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
RemoveFolderMemberError (open union)
access_error
member_error
folder_ownerVoidThe target user is the owner of the shared folder. You can't remove this user until ownership has been transferred to another member.
group_accessVoidThe target user has access to the shared folder via a group.
team_folderVoidThis action cannot be performed on a team shared folder.
no_permissionVoidThe current user does not have permission to perform this action.
too_many_filesVoidThis shared folder has too many files for leaving a copy. You can still remove this user without leaving a copy.
See also general errors.

/revoke_shared_link


Description

Revoke a shared link. Note that even after revoking a shared link to a file, the file may be accessible if there are shared links leading to any of the file parent folders. To list all shared links that enable access to a specific file, you can use the list_shared_links with the file as the ListSharedLinksArg.path argument.

URL Structure
https://api.dropboxapi.com/2/sharing/revoke_shared_link
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/revoke_shared_link \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"url\":\"https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0\"}"
Parameters
{
    "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
}
RevokeSharedLinkArg
urlStringURL of the shared link.
Returns
No return values.
Errors
Example: shared_link_not_found
{
    "error": {
        ".tag": "shared_link_not_found"
    },
    "error_summary": "shared_link_not_found/..."
}
Example: shared_link_access_denied
{
    "error": {
        ".tag": "shared_link_access_denied"
    },
    "error_summary": "shared_link_access_denied/..."
}
Example: unsupported_link_type
{
    "error": {
        ".tag": "unsupported_link_type"
    },
    "error_summary": "unsupported_link_type/..."
}
Example: unsupported_parameter_field
{
    "error": {
        ".tag": "unsupported_parameter_field"
    },
    "error_summary": "unsupported_parameter_field/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: shared_link_malformed
{
    "error": {
        ".tag": "shared_link_malformed"
    },
    "error_summary": "shared_link_malformed/..."
}
RevokeSharedLinkError (union)
shared_link_not_foundVoidThe shared link wasn't found.
shared_link_access_deniedVoidThe caller is not allowed to access this shared link.
unsupported_link_typeVoidThis type of link is not supported; use files.export instead.
unsupported_parameter_fieldVoidPrivate shared links do not support `path` or `link_password` parameter fields.
shared_link_malformedVoidShared link is malformed.
See also general errors.

/set_access_inheritance


Description

Change the inheritance policy of an existing Shared Folder. Only permitted for shared folders in a shared team root. If a ShareFolderLaunch.async_job_id is returned, you'll need to call check_share_job_status until the action completes to get the metadata for the folder.

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

URL Structure
https://api.dropboxapi.com/2/sharing/set_access_inheritance
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/set_access_inheritance \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"access_inheritance\":\"inherit\",\"shared_folder_id\":\"84528192421\"}"
Parameters
{
    "access_inheritance": "inherit",
    "shared_folder_id": "84528192421"
}
SetAccessInheritanceArg
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
access_inheritanceThe access inheritance settings for the folder. The default for this union is inherit.
Returns
{
    ".tag": "complete",
    "access_inheritance": {
        ".tag": "inherit"
    },
    "access_type": {
        ".tag": "owner"
    },
    "folder_id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_inside_team_folder": false,
    "is_team_folder": false,
    "link_metadata": {
        "audience_options": [
            {
                ".tag": "public"
            },
            {
                ".tag": "team"
            },
            {
                ".tag": "members"
            }
        ],
        "current_audience": {
            ".tag": "public"
        },
        "link_permissions": [
            {
                "action": {
                    ".tag": "change_audience"
                },
                "allow": true
            }
        ],
        "password_protected": false,
        "url": ""
    },
    "name": "dir",
    "path_lower": "/dir",
    "permissions": [],
    "policy": {
        "acl_update_policy": {
            ".tag": "owner"
        },
        "member_policy": {
            ".tag": "anyone"
        },
        "resolved_member_policy": {
            ".tag": "team"
        },
        "shared_link_policy": {
            ".tag": "anyone"
        }
    },
    "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
    "shared_folder_id": "84528192421",
    "time_invited": "2016-01-20T00:00:00Z"
}
ShareFolderLaunch (union)
async_job_idString(min_length=1)This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
complete
Errors
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
SetAccessInheritanceError (open union)
access_errorUnable to access shared folder.
no_permissionVoidThe current user does not have permission to perform this action.
See also general errors.

/share_folder


Description

Share a folder with collaborators. Most sharing will be completed synchronously. Large folders will be completed asynchronously. To make testing the async case repeatable, set `ShareFolderArg.force_async`. If a ShareFolderLaunch.async_job_id is returned, you'll need to call check_share_job_status until the action completes to get the metadata for the folder.

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

URL Structure
https://api.dropboxapi.com/2/sharing/share_folder
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/share_folder \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"access_inheritance\":\"inherit\",\"acl_update_policy\":\"editors\",\"force_async\":false,\"member_policy\":\"team\",\"path\":\"/example/workspace\",\"shared_link_policy\":\"members\"}"
Parameters
{
    "access_inheritance": "inherit",
    "acl_update_policy": "editors",
    "force_async": false,
    "member_policy": "team",
    "path": "/example/workspace",
    "shared_link_policy": "members"
}
ShareFolderArg
pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)")The path or the file id to the folder to share. If it does not exist, then a new one is created.
acl_update_policy?Who can add and remove members of this shared folder. This field is optional.
force_asyncBooleanWhether to force the share to happen asynchronously. The default for this field is False.
member_policy?Who can be a member of this shared folder. Only applicable if the current user is on a team. This field is optional.
shared_link_policy?The policy to apply to shared links created for content inside this shared folder. The current user must be on a team to set this policy to SharedLinkPolicy.members. This field is optional.
viewer_info_policy?Who can enable/disable viewer info for this shared folder. This field is optional.
access_inheritanceThe access inheritance settings for the folder. The default for this union is inherit.
actionsList of ()?A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the response's SharedFolderMetadata.permissions field describing the actions the authenticated user can perform on the folder. This field is optional.
link_settings?Settings on the link for this folder. This field is optional.
Returns
{
    ".tag": "complete",
    "access_inheritance": {
        ".tag": "inherit"
    },
    "access_type": {
        ".tag": "owner"
    },
    "folder_id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_inside_team_folder": false,
    "is_team_folder": false,
    "link_metadata": {
        "audience_options": [
            {
                ".tag": "public"
            },
            {
                ".tag": "team"
            },
            {
                ".tag": "members"
            }
        ],
        "current_audience": {
            ".tag": "public"
        },
        "link_permissions": [
            {
                "action": {
                    ".tag": "change_audience"
                },
                "allow": true
            }
        ],
        "password_protected": false,
        "url": ""
    },
    "name": "dir",
    "path_lower": "/dir",
    "permissions": [],
    "policy": {
        "acl_update_policy": {
            ".tag": "owner"
        },
        "member_policy": {
            ".tag": "anyone"
        },
        "resolved_member_policy": {
            ".tag": "team"
        },
        "shared_link_policy": {
            ".tag": "anyone"
        }
    },
    "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
    "shared_folder_id": "84528192421",
    "time_invited": "2016-01-20T00:00:00Z"
}
ShareFolderLaunch (union)
async_job_idString(min_length=1)This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
complete
Errors
Example: email_unverified
{
    "error": {
        ".tag": "email_unverified"
    },
    "error_summary": "email_unverified/..."
}
Example: team_policy_disallows_member_policy
{
    "error": {
        ".tag": "team_policy_disallows_member_policy"
    },
    "error_summary": "team_policy_disallows_member_policy/..."
}
Example: disallowed_shared_link_policy
{
    "error": {
        ".tag": "disallowed_shared_link_policy"
    },
    "error_summary": "disallowed_shared_link_policy/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
ShareFolderError (union)
email_unverifiedVoidThis user's email address is not verified. This functionality is only available on accounts with a verified email address. Users can verify their email address here.
bad_pathShareFolderArg.path is invalid.
team_policy_disallows_member_policyVoidTeam policy or group sharing settings are more restrictive than ShareFolderArg.member_policy.
disallowed_shared_link_policyVoidThe current user's account is not allowed to select the specified ShareFolderArg.shared_link_policy.
no_permissionVoidThe current user does not have permission to perform this action.
See also general errors.

/transfer_folder


Description

Transfer ownership of a shared folder to a member of the shared folder. User must have AccessLevel.owner access to the shared folder to perform a transfer.

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

URL Structure
https://api.dropboxapi.com/2/sharing/transfer_folder
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/transfer_folder \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"shared_folder_id\":\"84528192421\",\"to_dropbox_id\":\"dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q\"}"
Parameters
{
    "shared_folder_id": "84528192421",
    "to_dropbox_id": "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"
}
TransferFolderArg
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
to_dropbox_idString(min_length=1)A account or team member ID to transfer ownership to.
Returns
No return values.
Errors
Example: invalid_dropbox_id
{
    "error": {
        ".tag": "invalid_dropbox_id"
    },
    "error_summary": "invalid_dropbox_id/..."
}
Example: new_owner_not_a_member
{
    "error": {
        ".tag": "new_owner_not_a_member"
    },
    "error_summary": "new_owner_not_a_member/..."
}
Example: new_owner_unmounted
{
    "error": {
        ".tag": "new_owner_unmounted"
    },
    "error_summary": "new_owner_unmounted/..."
}
Example: new_owner_email_unverified
{
    "error": {
        ".tag": "new_owner_email_unverified"
    },
    "error_summary": "new_owner_email_unverified/..."
}
Example: team_folder
{
    "error": {
        ".tag": "team_folder"
    },
    "error_summary": "team_folder/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
TransferFolderError (open union)
access_error
invalid_dropbox_idVoidTransferFolderArg.to_dropbox_id is invalid.
new_owner_not_a_memberVoidThe new designated owner is not currently a member of the shared folder.
new_owner_unmountedVoidThe new designated owner has not added the folder to their Dropbox.
new_owner_email_unverifiedVoidThe new designated owner's email address is not verified. This functionality is only available on accounts with a verified email address. Users can verify their email address here.
team_folderVoidThis action cannot be performed on a team shared folder.
no_permissionVoidThe current user does not have permission to perform this action.
See also general errors.

/unmount_folder


Description

The current user unmounts the designated folder. They can re-mount the folder at a later time using mount_folder.

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

URL Structure
https://api.dropboxapi.com/2/sharing/unmount_folder
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/unmount_folder \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"shared_folder_id\":\"84528192421\"}"
Parameters
{
    "shared_folder_id": "84528192421"
}
UnmountFolderArg
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
Returns
No return values.
Errors
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: not_unmountable
{
    "error": {
        ".tag": "not_unmountable"
    },
    "error_summary": "not_unmountable/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UnmountFolderError (open union)
access_error
no_permissionVoidThe current user does not have permission to perform this action.
not_unmountableVoidThe shared folder can't be unmounted. One example where this can occur is when the shared folder's parent folder is also a shared folder that resides in the current user's Dropbox.
See also general errors.

/unshare_file


Description

Remove all members from this file. Does not remove inherited members.

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

URL Structure
https://api.dropboxapi.com/2/sharing/unshare_file
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/unshare_file \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"file\":\"id:3kmLmQFnf1AAAAAAAAAAAw\"}"
Parameters
{
    "file": "id:3kmLmQFnf1AAAAAAAAAAAw"
}
UnshareFileArg
Arguments for unshare_file.
fileString(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")The file to unshare.
Returns
No return values.
Errors
{
    "error": {
        ".tag": "user_error",
        "user_error": {
            ".tag": "email_unverified"
        }
    },
    "error_summary": "user_error/email_unverified/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UnshareFileError (open union)
Error result for unshare_file.
user_error
access_error
See also general errors.

/unshare_folder


Description

Allows a shared folder owner to unshare the folder. Unshare will not work in following cases: The shared folder contains shared folders OR the shared folder is inside another shared folder. You'll need to call check_job_status to determine if the action has completed successfully.

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

URL Structure
https://api.dropboxapi.com/2/sharing/unshare_folder
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/unshare_folder \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"leave_a_copy\":false,\"shared_folder_id\":\"84528192421\"}"
Parameters
{
    "leave_a_copy": false,
    "shared_folder_id": "84528192421"
}
UnshareFolderArg
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
leave_a_copyBooleanIf true, members of this shared folder will get a copy of this folder after it's unshared. Otherwise, it will be removed from their Dropbox. The current user, who is an owner, will always retain their copy. The default for this field is False.
Returns
Example: complete
{
    ".tag": "complete"
}
Example: async_job_id
{
    ".tag": "async_job_id",
    "async_job_id": "34g93hh34h04y384084"
}
LaunchEmptyResult (union)
Result returned by methods that may either launch an asynchronous job or complete synchronously. Upon synchronous completion of the job, no additional information is returned. This datatype comes from an imported namespace originally defined in the async namespace.
async_job_idString(min_length=1)This response indicates that the processing is asynchronous. The string is an id that can be used to obtain the status of the asynchronous job.
completeVoidThe job finished synchronously and successfully.
Errors
Example: team_folder
{
    "error": {
        ".tag": "team_folder"
    },
    "error_summary": "team_folder/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: too_many_files
{
    "error": {
        ".tag": "too_many_files"
    },
    "error_summary": "too_many_files/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UnshareFolderError (open union)
access_error
team_folderVoidThis action cannot be performed on a team shared folder.
no_permissionVoidThe current user does not have permission to perform this action.
too_many_filesVoidThis shared folder has too many files to be unshared.
See also general errors.

/update_file_member


Description

Changes a member's access on a shared file.

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

URL Structure
https://api.dropboxapi.com/2/sharing/update_file_member
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/update_file_member \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"access_level\":\"viewer\",\"file\":\"id:3kmLmQFnf1AAAAAAAAAAAw\",\"member\":{\".tag\":\"email\",\"email\":\"justin@example.com\"}}"
Parameters
{
    "access_level": "viewer",
    "file": "id:3kmLmQFnf1AAAAAAAAAAAw",
    "member": {
        ".tag": "email",
        "email": "justin@example.com"
    }
}
UpdateFileMemberArgs
Arguments for update_file_member.
fileString(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")File for which we are changing a member's access.
memberThe member whose access we are changing.
access_levelThe new access level for the member.
Returns
MemberAccessLevelResult
Contains information about a member's access level to content after an operation.
access_level?The member still has this level of access to the content through a parent folder. This field is optional.
warning String?A localized string with additional information about why the user has this access level to the content. This field is optional.
access_detailsList of ()?The parent folders that a member has access to. The field is present if the user has access to the first parent folder where the member gains access. This field is optional.
Errors
Example: invalid_member
{
    "error": {
        ".tag": "invalid_member"
    },
    "error_summary": "invalid_member/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
FileMemberActionError (open union)
invalid_memberVoidSpecified member was not found.
no_permissionVoidUser does not have permission to perform this action on this member.
access_errorSpecified file was invalid or user does not have access.
no_explicit_accessThe action cannot be completed because the target member does not have explicit access to the file. The return value is the access that the member has to the file from a parent folder.
See also general errors.

/update_folder_member


Description

Allows an owner or editor of a shared folder to update another member's permissions.

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

URL Structure
https://api.dropboxapi.com/2/sharing/update_folder_member
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/update_folder_member \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"access_level\":\"editor\",\"member\":{\".tag\":\"email\",\"email\":\"justin@example.com\"},\"shared_folder_id\":\"84528192421\"}"
Parameters
{
    "access_level": "editor",
    "member": {
        ".tag": "email",
        "email": "justin@example.com"
    },
    "shared_folder_id": "84528192421"
}
UpdateFolderMemberArg
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
memberThe member of the shared folder to update. Only the MemberSelector.dropbox_id may be set at this time.
access_levelThe new access level for member. AccessLevel.owner is disallowed.
Returns
MemberAccessLevelResult
Contains information about a member's access level to content after an operation.
access_level?The member still has this level of access to the content through a parent folder. This field is optional.
warning String?A localized string with additional information about why the user has this access level to the content. This field is optional.
access_detailsList of ()?The parent folders that a member has access to. The field is present if the user has access to the first parent folder where the member gains access. This field is optional.
Errors
Example: insufficient_plan
{
    "error": {
        ".tag": "insufficient_plan"
    },
    "error_summary": "insufficient_plan/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UpdateFolderMemberError (open union)
access_error
member_error
no_explicit_accessIf updating the access type required the member to be added to the shared folder and there was an error when adding the member.
insufficient_planVoidThe current user's account doesn't support this action. An example of this is when downgrading a member from editor to viewer. This action can only be performed by users that have upgraded to a Pro or Business plan.
no_permissionVoidThe current user does not have permission to perform this action.
See also general errors.

/update_folder_policy


Description

Update the sharing policies for a shared folder. User must have AccessLevel.owner access to the shared folder to update its policies.

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

URL Structure
https://api.dropboxapi.com/2/sharing/update_folder_policy
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/update_folder_policy \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"acl_update_policy\":\"owner\",\"member_policy\":\"team\",\"shared_folder_id\":\"84528192421\",\"shared_link_policy\":\"members\"}"
Parameters
{
    "acl_update_policy": "owner",
    "member_policy": "team",
    "shared_folder_id": "84528192421",
    "shared_link_policy": "members"
}
UpdateFolderPolicyArg
If any of the policies are unset, then they retain their current setting.
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID for the shared folder.
member_policy?Who can be a member of this shared folder. Only applicable if the current user is on a team. This field is optional.
acl_update_policy?Who can add and remove members of this shared folder. This field is optional.
viewer_info_policy?Who can enable/disable viewer info for this shared folder. This field is optional.
shared_link_policy?The policy to apply to shared links created for content inside this shared folder. The current user must be on a team to set this policy to SharedLinkPolicy.members. This field is optional.
link_settings?Settings on the link for this folder. This field is optional.
actionsList of ()?A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the response's SharedFolderMetadata.permissions field describing the actions the authenticated user can perform on the folder. This field is optional.
Returns
{
    "access_inheritance": {
        ".tag": "inherit"
    },
    "access_type": {
        ".tag": "owner"
    },
    "folder_id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_inside_team_folder": false,
    "is_team_folder": false,
    "link_metadata": {
        "audience_options": [
            {
                ".tag": "public"
            },
            {
                ".tag": "team"
            },
            {
                ".tag": "members"
            }
        ],
        "current_audience": {
            ".tag": "public"
        },
        "link_permissions": [
            {
                "action": {
                    ".tag": "change_audience"
                },
                "allow": true
            }
        ],
        "password_protected": false,
        "url": ""
    },
    "name": "dir",
    "path_lower": "/dir",
    "permissions": [],
    "policy": {
        "acl_update_policy": {
            ".tag": "owner"
        },
        "member_policy": {
            ".tag": "anyone"
        },
        "resolved_member_policy": {
            ".tag": "team"
        },
        "shared_link_policy": {
            ".tag": "anyone"
        }
    },
    "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
    "shared_folder_id": "84528192421",
    "time_invited": "2016-01-20T00:00:00Z"
}
SharedFolderMetadata
The metadata which includes basic information about the shared folder.
access_typeThe current user's access level for this shared folder.
is_inside_team_folderBooleanWhether this folder is inside of a team folder.
is_team_folderBooleanWhether this folder is a team folder.
nameStringThe name of the this shared folder.
policyPolicies governing this shared folder.
preview_urlStringURL for displaying a web preview of the shared folder.
shared_folder_idString(pattern="[-_0-9a-zA-Z:]+")The ID of the shared folder.
time_invitedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")Timestamp indicating when the current user was invited to this shared folder.
owner_display_names List of (String)?The display names of the users that own the folder. If the folder is part of a team folder, the display names of the team admins are also included. Absent if the owner display names cannot be fetched. This field is optional.
owner_team?The team that owns the folder. This field is not present if the folder is not owned by a team. This field is optional.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")?The ID of the parent shared folder. This field is present only if the folder is contained within another shared folder. This field is optional.
path_display String?The full path of this shared folder. Absent for unmounted folders. This field is optional.
path_lower String?The lower-cased full path of this shared folder. Absent for unmounted folders. This field is optional.
parent_folder_name String?Display name for the parent folder. This field is optional.
link_metadata?The metadata of the shared content link to this shared folder. Absent if there is no link on the folder. This is for an unreleased feature so it may not be returned yet. This field is optional.
permissionsList of ()?Actions the current user may perform on the folder and its contents. The set of permissions corresponds to the FolderActions in the request. This field is optional.
access_inheritanceWhether the folder inherits its members from its parent. The default for this union is inherit.
folder_id String(min_length=4, pattern="id:.+")?The ID of the content. This field is optional.
Errors
Example: not_on_team
{
    "error": {
        ".tag": "not_on_team"
    },
    "error_summary": "not_on_team/..."
}
Example: team_policy_disallows_member_policy
{
    "error": {
        ".tag": "team_policy_disallows_member_policy"
    },
    "error_summary": "team_policy_disallows_member_policy/..."
}
Example: disallowed_shared_link_policy
{
    "error": {
        ".tag": "disallowed_shared_link_policy"
    },
    "error_summary": "disallowed_shared_link_policy/..."
}
Example: no_permission
{
    "error": {
        ".tag": "no_permission"
    },
    "error_summary": "no_permission/..."
}
Example: team_folder
{
    "error": {
        ".tag": "team_folder"
    },
    "error_summary": "team_folder/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UpdateFolderPolicyError (open union)
access_error
not_on_teamVoidUpdateFolderPolicyArg.member_policy was set even though user is not on a team.
team_policy_disallows_member_policyVoidTeam policy or group sharing settings are more restrictive than ShareFolderArg.member_policy.
disallowed_shared_link_policyVoidThe current account is not allowed to select the specified ShareFolderArg.shared_link_policy.
no_permissionVoidThe current user does not have permission to perform this action.
team_folderVoidThis action cannot be performed on a team shared folder.
See also general errors.

users

This namespace contains endpoints and data types for user management.

/features/get_values


Description

Get a list of feature values that may be configured for the current account.

URL Structure
https://api.dropboxapi.com/2/users/features/get_values
Authentication
User Authentication
Endpoint format
RPC
Required Scope
account_info.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/users/features/get_values \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"features\":[{\".tag\":\"paper_as_files\"},{\".tag\":\"file_locking\"}]}"
Parameters
{
    "features": [
        {
            ".tag": "paper_as_files"
        },
        {
            ".tag": "file_locking"
        }
    ]
}
UserFeaturesGetValuesBatchArg
featuresList of ()A list of features in UserFeature. If the list is empty, this route will return UserFeaturesGetValuesBatchError.
Returns
{
    "values": [
        {
            ".tag": "paper_as_files",
            "paper_as_files": {
                ".tag": "enabled",
                "enabled": true
            }
        }
    ]
}
UserFeaturesGetValuesBatchResult
valuesList of ()
Errors
Example: empty_features_list
{
    "error": {
        ".tag": "empty_features_list"
    },
    "error_summary": "empty_features_list/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UserFeaturesGetValuesBatchError (open union)
empty_features_listVoidAt least one UserFeature must be included in the UserFeaturesGetValuesBatchArg.features list.
See also general errors.

/get_account


Description

Get information about a user's account.

URL Structure
https://api.dropboxapi.com/2/users/get_account
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/users/get_account \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"account_id\":\"dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc\"}"
Parameters
{
    "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
}
GetAccountArg
account_idString(min_length=40, max_length=40)A user's account identifier.
Returns
{
    "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
    "disabled": false,
    "email": "franz@dropbox.com",
    "email_verified": true,
    "is_teammate": false,
    "name": {
        "abbreviated_name": "FF",
        "display_name": "Franz Ferdinand (Personal)",
        "familiar_name": "Franz",
        "given_name": "Franz",
        "surname": "Ferdinand"
    },
    "profile_photo_url": "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128"
}
Example: team
{
    "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
    "disabled": false,
    "email": "franz@dropbox.com",
    "email_verified": true,
    "is_teammate": true,
    "name": {
        "abbreviated_name": "FF",
        "display_name": "Franz Ferdinand (Personal)",
        "familiar_name": "Franz",
        "given_name": "Franz",
        "surname": "Ferdinand"
    },
    "profile_photo_url": "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128",
    "team_member_id": "dbmid:AAHhy7WsR0x-u4ZCqiDl5Fz5zvuL3kmspwU"
}
BasicAccount
Basic information about any account.
account_idString(min_length=40, max_length=40)The user's unique Dropbox ID.
nameDetails of a user's name.
emailStringThe user's email address. Do not rely on this without checking the email_verified field. Even then, it's possible that the user has since lost access to their email.
email_verifiedBooleanWhether the user has verified their email address.
disabledBooleanWhether the user has been disabled.
is_teammateBooleanWhether this user is a teammate of the current user. If this account is the current user's account, then this will be true.
profile_photo_url String?URL for the photo representing the user, if one is set. This field is optional.
team_member_id String?The user's unique team member id. This field will only be present if the user is part of a team and is_teammate is true. This field is optional.
Errors
Example: no_account
{
    "error": {
        ".tag": "no_account"
    },
    "error_summary": "no_account/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
GetAccountError (open union)
no_accountVoidThe specified GetAccountArg.account_id does not exist.
See also general errors.

/get_account_batch


Description

Get information about multiple user accounts. At most 300 accounts may be queried per request.

URL Structure
https://api.dropboxapi.com/2/users/get_account_batch
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/users/get_account_batch \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"account_ids\":[\"dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc\",\"dbid:AAH1Vcz-DVoRDeixtr_OA8oUGgiqhs4XPOQ\"]}"
Parameters
{
    "account_ids": [
        "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "dbid:AAH1Vcz-DVoRDeixtr_OA8oUGgiqhs4XPOQ"
    ]
}
GetAccountBatchArg
account_ids List of (String(min_length=40, max_length=40), min_items=1)List of user account identifiers. Should not contain any duplicate account IDs.
Returns
List of (BasicAccount)
Basic information about any account.
account_idString(min_length=40, max_length=40)The user's unique Dropbox ID.
nameDetails of a user's name.
emailStringThe user's email address. Do not rely on this without checking the email_verified field. Even then, it's possible that the user has since lost access to their email.
email_verifiedBooleanWhether the user has verified their email address.
disabledBooleanWhether the user has been disabled.
is_teammateBooleanWhether this user is a teammate of the current user. If this account is the current user's account, then this will be true.
profile_photo_url String?URL for the photo representing the user, if one is set. This field is optional.
team_member_id String?The user's unique team member id. This field will only be present if the user is part of a team and is_teammate is true. This field is optional.
Errors
{
    "error": {
        ".tag": "no_account",
        "no_account": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
    },
    "error_summary": "no_account/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
GetAccountBatchError (open union)
no_accountString(min_length=40, max_length=40)The value is an account ID specified in GetAccountBatchArg.account_ids that does not exist.
See also general errors.

/get_current_account


Description

Get information about the current user's account.

URL Structure
https://api.dropboxapi.com/2/users/get_current_account
Authentication
User Authentication, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Required Scope
account_info.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/users/get_current_account \
    --header "Authorization: Bearer <get access token>"
Parameters
No parameters.
Returns
Example: Paired account.
{
    "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
    "account_type": {
        ".tag": "business"
    },
    "country": "US",
    "disabled": false,
    "email": "franz@dropbox.com",
    "email_verified": true,
    "is_paired": true,
    "locale": "en",
    "name": {
        "abbreviated_name": "FF",
        "display_name": "Franz Ferdinand (Personal)",
        "familiar_name": "Franz",
        "given_name": "Franz",
        "surname": "Ferdinand"
    },
    "referral_link": "https://db.tt/ZITNuhtI",
    "root_info": {
        ".tag": "user",
        "home_namespace_id": "3235641",
        "root_namespace_id": "3235641"
    },
    "team": {
        "id": "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I",
        "name": "Acme, Inc.",
        "office_addin_policy": {
            ".tag": "disabled"
        },
        "sharing_policies": {
            "default_link_expiration_days_policy": {
                ".tag": "none"
            },
            "enforce_link_password_policy": {
                ".tag": "optional"
            },
            "group_creation_policy": {
                ".tag": "admins_only"
            },
            "shared_folder_join_policy": {
                ".tag": "from_anyone"
            },
            "shared_folder_link_restriction_policy": {
                ".tag": "anyone"
            },
            "shared_folder_member_policy": {
                ".tag": "team"
            },
            "shared_link_create_policy": {
                ".tag": "team_only"
            },
            "shared_link_default_permissions_policy": {
                ".tag": "default"
            }
        },
        "top_level_content_policy": {
            ".tag": "admin_only"
        }
    },
    "team_member_id": "dbmid:AAHhy7WsR0x-u4ZCqiDl5Fz5zvuL3kmspwU"
}
Example: A personal account that is not paired with a team.
{
    "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
    "account_type": {
        ".tag": "basic"
    },
    "country": "US",
    "disabled": false,
    "email": "franz@gmail.com",
    "email_verified": false,
    "is_paired": false,
    "locale": "en",
    "name": {
        "abbreviated_name": "FF",
        "display_name": "Franz Ferdinand (Personal)",
        "familiar_name": "Franz",
        "given_name": "Franz",
        "surname": "Ferdinand"
    },
    "profile_photo_url": "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128",
    "referral_link": "https://db.tt/ZITNuhtI",
    "root_info": {
        ".tag": "user",
        "home_namespace_id": "3235641",
        "root_namespace_id": "3235641"
    }
}
FullAccount
Detailed information about the current user's account.
account_idString(min_length=40, max_length=40)The user's unique Dropbox ID.
nameDetails of a user's name.
emailStringThe user's email address. Do not rely on this without checking the email_verified field. Even then, it's possible that the user has since lost access to their email.
email_verifiedBooleanWhether the user has verified their email address.
disabledBooleanWhether the user has been disabled.
localeString(min_length=2)The language that the user specified. Locale tags will be IETF language tags.
referral_linkStringThe user's referral link.
is_pairedBooleanWhether the user has a personal and work account. If the current account is personal, then team will always be None, but is_paired will indicate if a work account is linked.
account_typeWhat type of account this user has.
root_infoThe root info for this account.
profile_photo_url String?URL for the photo representing the user, if one is set. This field is optional.
country String(min_length=2, max_length=2)?The user's two-letter country code, if available. Country codes are based on ISO 3166-1. This field is optional.
team?If this account is a member of a team, information about that team. This field is optional.
team_member_id String?This account's unique team member id. This field will only be present if team is present. This field is optional.
Errors
No endpoint-specific errors.
See also general errors.

/get_space_usage


Description

Get the space usage information for the current user's account.

URL Structure
https://api.dropboxapi.com/2/users/get_space_usage
Authentication
User Authentication
Endpoint format
RPC
Required Scope
account_info.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/users/get_space_usage \
    --header "Authorization: Bearer <get access token>"
Parameters
No parameters.
Returns
{
    "allocation": {
        ".tag": "individual",
        "allocated": 10000000000
    },
    "used": 314159265
}
SpaceUsage
Information about a user's space usage and quota.
usedUInt64The user's total space usage (bytes).
allocationThe user's space allocation.
Errors
No endpoint-specific errors.
See also general errors.

Deprecated

All deprecated endpoints, across namespaces

Deprecated: auth

Deprecated endpoints for auth

/token/from_oauth1


"DEPRECATED"
Description

Creates an OAuth 2.0 access token from the supplied OAuth 1.0 access token.

URL Structure
https://api.dropboxapi.com/2/auth/token/from_oauth1
Authentication
App Authentication
Endpoint format
RPC
Required Scope
None
Example
Get app key and secret for:
curl -X POST https://api.dropboxapi.com/2/auth/token/from_oauth1 \
    --header "Authorization: Basic <get app key and secret>" \
    --header "Content-Type: application/json" \
    --data "{\"oauth1_token\":\"qievr8hamyg6ndck\",\"oauth1_token_secret\":\"qomoftv0472git7\"}"
Parameters
{
    "oauth1_token": "qievr8hamyg6ndck",
    "oauth1_token_secret": "qomoftv0472git7"
}
TokenFromOAuth1Arg
oauth1_tokenString(min_length=1)The supplied OAuth 1.0 access token.
oauth1_token_secretString(min_length=1)The token secret associated with the supplied access token.
Returns
{
    "oauth2_token": "9mCrkS7BIdAAAAAAAAAAHHS0TsSnpYvKQVtKdBnN5IuzhYOGblSgTcHgBFKFMmFn"
}
TokenFromOAuth1Result
oauth2_tokenString(min_length=1)The OAuth 2.0 token generated from the supplied OAuth 1.0 token.
Errors
Example: invalid_oauth1_token_info
{
    "error": {
        ".tag": "invalid_oauth1_token_info"
    },
    "error_summary": "invalid_oauth1_token_info/..."
}
Example: app_id_mismatch
{
    "error": {
        ".tag": "app_id_mismatch"
    },
    "error_summary": "app_id_mismatch/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
TokenFromOAuth1Error (open union)
invalid_oauth1_token_infoVoidPart or all of the OAuth 1.0 access token info is invalid.
app_id_mismatchVoidThe authorized app does not match the app associated with the supplied access token.
See also general errors.

Deprecated: files

Deprecated endpoints for files

/alpha/get_metadata


PREVIEW - may change or disappear without notice
DEPRECATED BY /get_metadata
Description

Returns the metadata for a file or folder. This is an alpha endpoint compatible with the properties API. Note: Metadata for the root folder is unsupported.

URL Structure
https://api.dropboxapi.com/2/files/alpha/get_metadata
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/alpha/get_metadata \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"include_deleted\":false,\"include_has_explicit_shared_members\":false,\"include_media_info\":false,\"path\":\"/Homework/math\"}"
Parameters
{
    "include_deleted": false,
    "include_has_explicit_shared_members": false,
    "include_media_info": false,
    "path": "/Homework/math"
}
Example: id
{
    "include_deleted": false,
    "include_has_explicit_shared_members": false,
    "include_media_info": false,
    "path": "id:a4ayc_80_OEAAAAAAAAAYa"
}
Example: rev
{
    "include_deleted": false,
    "include_has_explicit_shared_members": false,
    "include_media_info": false,
    "path": "rev:a1c10ce0dd78"
}
AlphaGetMetadataArg
pathString(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")The path of a file or folder on Dropbox.
include_media_infoBooleanIf true, FileMetadata.media_info is set for photo and video. The default for this field is False.
include_deletedBooleanIf true, DeletedMetadata will be returned for deleted file or folder, otherwise LookupError.not_found will be returned. The default for this field is False.
include_has_explicit_shared_membersBooleanIf true, the results will include a flag for each file indicating whether or not that file has any explicit members. The default for this field is False.
include_property_groups?If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates. This field is optional.
include_property_templatesdeprecated List of (String(min_length=1, pattern="(/|ptid:).*"))?Field is deprecated. If set to a valid list of template IDs, FileMetadata.property_groups is set for files with custom properties. This field is optional.
Returns
{
    ".tag": "file",
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "file_lock_info": {
        "created": "2015-05-12T15:50:38Z",
        "is_lockholder": true,
        "lockholder_name": "Imaginary User"
    },
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
{
    ".tag": "folder",
    "id": "id:a4ayc_80_OEAAAAAAAAAXz",
    "name": "math",
    "path_display": "/Homework/math",
    "path_lower": "/homework/math",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "sharing_info": {
        "no_access": false,
        "parent_shared_folder_id": "84528192421",
        "read_only": false,
        "traverse_only": false
    }
}
Example: search_file_metadata
{
    ".tag": "file",
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
Metadata (datatype with subtypes)
Metadata for a file or folder.
file
folder
deleted
Errors
AlphaGetMetadataError (union)
path
properties_error
See also general errors.

/alpha/upload


PREVIEW - may change or disappear without notice
DEPRECATED BY /upload
Description

Create a new file with the contents provided in the request. Note that the behavior of this alpha endpoint is unstable and subject to change. Do not use this to upload a file larger than 150 MiB. Instead, create an upload session with upload_session/start.

URL Structure
https://content.dropboxapi.com/2/files/alpha/upload
Authentication
User Authentication
Endpoint format
Content-upload
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/alpha/upload \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"autorename\":false,\"mode\":\"add\",\"mute\":false,\"path\":\"/Homework/math/Matrices.txt\",\"strict_conflict\":false}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "autorename": false,
    "mode": "add",
    "mute": false,
    "path": "/Homework/math/Matrices.txt",
    "strict_conflict": false
}
UploadArg
pathString(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)")Path in the user's Dropbox to save the file.
modeSelects what to do if the file already exists. The default for this union is add.
autorenameBooleanIf there's a conflict, as determined by mode, have the Dropbox server try to autorename the file to avoid conflict. The default for this field is False.
client_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ")?The value to store as the client_modified timestamp. Dropbox automatically records the time at which the file was written to the Dropbox servers. It can also record an additional timestamp, provided by Dropbox desktop clients, mobile clients, and API apps of when the file was actually created or modified. This field is optional.
muteBooleanNormally, users are made aware of any file modifications in their Dropbox account via notifications in the client software. If true, this tells the clients that this modification shouldn't result in a user notification. The default for this field is False.
property_groupsList of ()?List of custom properties to add to file. This field is optional.
strict_conflictBooleanBe more strict about how each WriteMode detects conflict. For example, always return a conflict error when mode = WriteMode.update and the given "rev" doesn't match the existing file's "rev", even if the existing file has been deleted. This also forces a conflict even when the target path refers to a file with identical contents. The default for this field is False.
content_hash String(min_length=64, max_length=64)?A hash of the file content uploaded in this call. If provided and the uploaded content does not match this hash, an error will be returned. For more information see our Content hash page. This field is optional.
Returns
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "file_lock_info": {
        "created": "2015-05-12T15:50:38Z",
        "is_lockholder": true,
        "lockholder_name": "Imaginary User"
    },
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ],
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
Example: search_file_metadata
{
    "client_modified": "2015-05-12T15:50:38Z",
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "has_explicit_shared_members": false,
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "is_downloadable": true,
    "name": "Prime_Numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "path_lower": "/homework/math/prime_numbers.txt",
    "rev": "a1c10ce0dd78",
    "server_modified": "2015-05-12T15:50:38Z",
    "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
    },
    "size": 7212
}
FileMetadata
nameStringThe last component of the path (including extension). This never contains a slash.
idString(min_length=1)A unique identifier for the file.
client_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")For files, this is the modification time set by the desktop client when the file was added to Dropbox. Since this time is not verified (the Dropbox server stores whatever the desktop client sends up), this should only be used for display purposes (such as sorting) and not, for example, to determine if a file has changed or not.
server_modifiedTimestamp(format="%Y-%m-%dT%H:%M:%SZ")The last time the file was modified on Dropbox.
revString(min_length=9, pattern="[0-9a-f]+")A unique identifier for the current revision of a file. This field is the same rev as elsewhere in the API and can be used to detect changes and avoid conflicts.
sizeUInt64The file size in bytes.
path_lower String?The lowercased full path in the user's Dropbox. This always starts with a slash. This field will be null if the file or folder is not mounted. This field is optional.
path_display String?The cased path to be used for display purposes only. In rare instances the casing will not correctly match the user's filesystem, but this behavior will match the path provided in the Core API v1, and at least the last path component will have the correct casing. Changes to only the casing of paths won't be returned by list_folder/continue. This field will be null if the file or folder is not mounted. This field is optional.
parent_shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")?Field is deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
preview_url String?The preview URL of the file. This field is optional.
media_info?Additional information if the file is a photo or video. This field will not be set on entries returned by list_folder, list_folder/continue, or get_thumbnail_batch, starting December 2, 2019. This field is optional.
symlink_info?Set if this file is a symlink. This field is optional.
sharing_info?Set if this file is contained in a shared folder. This field is optional.
is_downloadableBooleanIf true, file can be downloaded directly; else the file must be exported. The default for this field is True.
export_info?Information about format this file can be exported to. This filed must be set if is_downloadable is set to false. This field is optional.
property_groupsList of ()?Additional information if the file has custom properties with the property template specified. This field is optional.
has_explicit_shared_members Boolean?This flag will only be present if include_has_explicit_shared_members is true in list_folder or get_metadata. If this flag is present, it will be true if this file has any explicit shared members. This is different from sharing_info in that this could be true in the case where a file has explicit members but is not contained within a shared folder. This field is optional.
content_hash String(min_length=64, max_length=64)?A hash of the file content. This field can be used to verify data integrity. For more information see our Content hash page. This field is optional.
file_lock_info?If present, the metadata associated with the file's current lock. This field is optional.
Errors
Example: payload_too_large
{
    "error": {
        ".tag": "payload_too_large"
    },
    "error_summary": "payload_too_large/..."
}
Example: content_hash_mismatch
{
    "error": {
        ".tag": "content_hash_mismatch"
    },
    "error_summary": "content_hash_mismatch/..."
}
Example: encryption_not_supported
{
    "error": {
        ".tag": "encryption_not_supported"
    },
    "error_summary": "encryption_not_supported/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
UploadError (open union)
pathUnable to save the uploaded contents to a file.
properties_errorThe supplied property group is invalid. The file has uploaded without property groups.
payload_too_largeVoidThe request payload must be at most 150 MiB.
content_hash_mismatchVoidThe content received by the Dropbox server in this call does not match the provided content hash.
encryption_not_supportedVoidThe file is required to be encrypted, which is not supported in our public API.
See also general errors.

/properties/add


"DEPRECATED"
Description

No description

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

URL Structure
https://api.dropboxapi.com/2/files/properties/add
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/properties/add \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/my_awesome/word.docx\",\"property_groups\":[{\"fields\":[{\"name\":\"Security Policy\",\"value\":\"Confidential\"}],\"template_id\":\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ]
}
AddPropertiesArg
This datatype comes from an imported namespace originally defined in the file_properties namespace.
pathString(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)")A unique identifier for the file or folder.
property_groupsList of ()The property groups which are to be added to a Dropbox file. No two groups in the input should refer to the same template.
Returns
No return values.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: unsupported_folder
{
    "error": {
        ".tag": "unsupported_folder"
    },
    "error_summary": "unsupported_folder/..."
}
Example: property_field_too_large
{
    "error": {
        ".tag": "property_field_too_large"
    },
    "error_summary": "property_field_too_large/..."
}
Example: does_not_fit_template
{
    "error": {
        ".tag": "does_not_fit_template"
    },
    "error_summary": "does_not_fit_template/..."
}
Example: duplicate_property_groups
{
    "error": {
        ".tag": "duplicate_property_groups"
    },
    "error_summary": "duplicate_property_groups/..."
}
Example: property_group_already_exists
{
    "error": {
        ".tag": "property_group_already_exists"
    },
    "error_summary": "property_group_already_exists/..."
}
AddPropertiesError (union)
This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
path
unsupported_folderVoidThis folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_field_too_largeVoidOne or more of the supplied property field values is too large.
does_not_fit_templateVoidOne or more of the supplied property fields does not conform to the template specifications.
duplicate_property_groupsVoidThere are 2 or more property groups referring to the same templates in the input.
property_group_already_existsVoidA property group associated with this template and file already exists.
See also general errors.

/properties/overwrite


"DEPRECATED"
Description

No description

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

URL Structure
https://api.dropboxapi.com/2/files/properties/overwrite
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/properties/overwrite \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/my_awesome/word.docx\",\"property_groups\":[{\"fields\":[{\"name\":\"Security Policy\",\"value\":\"Confidential\"}],\"template_id\":\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "property_groups": [
        {
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ]
}
OverwritePropertyGroupArg
This datatype comes from an imported namespace originally defined in the file_properties namespace.
pathString(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)")A unique identifier for the file or folder.
property_groupsList of (, min_items=1)The property groups "snapshot" updates to force apply. No two groups in the input should refer to the same template.
Returns
No return values.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: unsupported_folder
{
    "error": {
        ".tag": "unsupported_folder"
    },
    "error_summary": "unsupported_folder/..."
}
Example: property_field_too_large
{
    "error": {
        ".tag": "property_field_too_large"
    },
    "error_summary": "property_field_too_large/..."
}
Example: does_not_fit_template
{
    "error": {
        ".tag": "does_not_fit_template"
    },
    "error_summary": "does_not_fit_template/..."
}
Example: duplicate_property_groups
{
    "error": {
        ".tag": "duplicate_property_groups"
    },
    "error_summary": "duplicate_property_groups/..."
}
InvalidPropertyGroupError (union)
This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
path
unsupported_folderVoidThis folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_field_too_largeVoidOne or more of the supplied property field values is too large.
does_not_fit_templateVoidOne or more of the supplied property fields does not conform to the template specifications.
duplicate_property_groupsVoidThere are 2 or more property groups referring to the same templates in the input.
See also general errors.

/properties/remove


"DEPRECATED"
Description

No description

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

URL Structure
https://api.dropboxapi.com/2/files/properties/remove
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/properties/remove \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/my_awesome/word.docx\",\"property_template_ids\":[\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "property_template_ids": [
        "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
    ]
}
RemovePropertiesArg
This datatype comes from an imported namespace originally defined in the file_properties namespace.
pathString(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)")A unique identifier for the file or folder.
property_template_ids List of (String(min_length=1, pattern="(/|ptid:).*"))A list of identifiers for a template created by templates/add_for_user or templates/add_for_team.
Returns
No return values.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: unsupported_folder
{
    "error": {
        ".tag": "unsupported_folder"
    },
    "error_summary": "unsupported_folder/..."
}
RemovePropertiesError (union)
This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
path
unsupported_folderVoidThis folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_group_lookup
See also general errors.

/properties/template/get


"DEPRECATED"
Description

No description

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

URL Structure
https://api.dropboxapi.com/2/files/properties/template/get
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/properties/template/get \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"template_id\":\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}"
Parameters
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
GetTemplateArg
This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_idString(min_length=1, pattern="(/|ptid:).*")An identifier for template added by route See templates/add_for_user or templates/add_for_team.
Returns
{
    "description": "These properties describe how confidential this file or folder is.",
    "fields": [
        {
            "description": "This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.",
            "name": "Security Policy",
            "type": {
                ".tag": "string"
            }
        }
    ],
    "name": "Security"
}
GetTemplateResult
This datatype comes from an imported namespace originally defined in the file_properties namespace.
nameStringDisplay name for the template. Template names can be up to 256 bytes.
descriptionStringDescription for the template. Template descriptions can be up to 1024 bytes.
fieldsList of ()Definitions of the property fields associated with this template. There can be up to 32 properties in a single template.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
TemplateError (open union)
This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
See also general errors.

/properties/template/list


"DEPRECATED"
Description

No description

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

URL Structure
https://api.dropboxapi.com/2/files/properties/template/list
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/properties/template/list \
    --header "Authorization: Bearer <get access token>"
Parameters
No parameters.
Returns
{
    "template_ids": [
        "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
    ]
}
ListTemplateResult
This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_ids List of (String(min_length=1, pattern="(/|ptid:).*"))List of identifiers for templates added by See templates/add_for_user or templates/add_for_team.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
TemplateError (open union)
This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
See also general errors.

/properties/update


"DEPRECATED"
Description

No description

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

URL Structure
https://api.dropboxapi.com/2/files/properties/update
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/properties/update \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/my_awesome/word.docx\",\"update_property_groups\":[{\"add_or_update_fields\":[{\"name\":\"Security Policy\",\"value\":\"Confidential\"}],\"remove_fields\":[],\"template_id\":\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "update_property_groups": [
        {
            "add_or_update_fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "remove_fields": [],
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
    ]
}
UpdatePropertiesArg
This datatype comes from an imported namespace originally defined in the file_properties namespace.
pathString(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)")A unique identifier for the file or folder.
update_property_groupsList of ()The property groups "delta" updates to apply.
Returns
No return values.
Errors
Example: restricted_content
{
    "error": {
        ".tag": "restricted_content"
    },
    "error_summary": "restricted_content/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: unsupported_folder
{
    "error": {
        ".tag": "unsupported_folder"
    },
    "error_summary": "unsupported_folder/..."
}
Example: property_field_too_large
{
    "error": {
        ".tag": "property_field_too_large"
    },
    "error_summary": "property_field_too_large/..."
}
Example: does_not_fit_template
{
    "error": {
        ".tag": "does_not_fit_template"
    },
    "error_summary": "does_not_fit_template/..."
}
Example: duplicate_property_groups
{
    "error": {
        ".tag": "duplicate_property_groups"
    },
    "error_summary": "duplicate_property_groups/..."
}
UpdatePropertiesError (union)
This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_not_foundString(min_length=1, pattern="(/|ptid:).*")Template does not exist for the given identifier.
restricted_contentVoidYou do not have permission to modify this template.
path
unsupported_folderVoidThis folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_field_too_largeVoidOne or more of the supplied property field values is too large.
does_not_fit_templateVoidOne or more of the supplied property fields does not conform to the template specifications.
duplicate_property_groupsVoidThere are 2 or more property groups referring to the same templates in the input.
property_group_lookup
See also general errors.

Deprecated: paper

Deprecated endpoints for paper

/docs/archive


"DEPRECATED"
Description

Marks the given Paper doc as archived. This action can be performed or undone by anyone with edit permissions to the doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. This endpoint will be retired in September 2020. Refer to the Paper Migration Guide for more information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/archive
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/archive \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
RefPaperDoc
doc_idStringThe Paper doc ID.
Returns
No return values.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
DocLookupError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
See also general errors.

/docs/create


"DEPRECATED"
Description

Creates a new Paper doc with the provided content. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. This endpoint will be retired in September 2020. Refer to the Paper Migration Guide for more information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/create
Authentication
User Authentication
Endpoint format
Content-upload
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/create \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"import_format\":\"markdown\"}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
Example: Create new Paper doc (unfiled).
{
    "import_format": "markdown"
}
Example: Create new Paper doc inside Paper folder.
{
    "import_format": "html",
    "parent_folder_id": "e.gGYT6HSafpMej9bUv306GarglI7GGeAM3yvfZvXHO9u4mV"
}
PaperDocCreateArgs
import_formatThe format of provided data.
parent_folder_id String?The Paper folder ID where the Paper document should be created. The API user has to have write access to this folder or error is thrown. This field is optional.
Returns
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "revision": 456736745,
    "title": "Week one retention"
}
PaperDocCreateUpdateResult
doc_idStringDoc ID of the newly created doc.
revisionInt64The Paper doc revision. Simply an ever increasing number.
titleStringThe Paper doc title.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: content_malformed
{
    "error": {
        ".tag": "content_malformed"
    },
    "error_summary": "content_malformed/..."
}
Example: folder_not_found
{
    "error": {
        ".tag": "folder_not_found"
    },
    "error_summary": "folder_not_found/..."
}
Example: doc_length_exceeded
{
    "error": {
        ".tag": "doc_length_exceeded"
    },
    "error_summary": "doc_length_exceeded/..."
}
Example: image_size_exceeded
{
    "error": {
        ".tag": "image_size_exceeded"
    },
    "error_summary": "image_size_exceeded/..."
}
PaperDocCreateError (union)
insufficient_permissionsVoidYour 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.
content_malformedVoidThe provided content was malformed and cannot be imported to Paper.
folder_not_foundVoidThe specified Paper folder is cannot be found.
doc_length_exceededVoidThe newly created Paper doc would be too large. Please split the content into multiple docs.
image_size_exceededVoidThe imported document contains an image that is too large. The current limit is 1MB. This only applies to HTML with data URI.
See also general errors.

/docs/download


"DEPRECATED"
Description

Exports and downloads Paper doc either as HTML or markdown. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/download
Authentication
User Authentication
Endpoint format
Content-download
Required Scope
files.content.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/download \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\",\"export_format\":\"markdown\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "export_format": "markdown"
}
PaperDocExport
doc_idStringThe Paper doc ID.
export_format
Returns
{
    "mime_type": "text/x-markdown",
    "owner": "james@example.com",
    "revision": 456736745,
    "title": "Week one retention"
}
PaperDocExportResult
ownerStringThe Paper doc owner's email address.
titleStringThe Paper doc title.
revisionInt64The Paper doc revision. Simply an ever increasing number.
mime_typeStringMIME type of the export. This corresponds to ExportFormat specified in the request.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
DocLookupError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
See also general errors.

/docs/folder_users/list


"DEPRECATED"
Description

Lists the users who are explicitly invited to the Paper folder in which the Paper doc is contained. For private folders all users (including owner) shared on the folder are listed and for team folders all non-team users shared on the folder are returned. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/folder_users/list
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/folder_users/list \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\",\"limit\":100}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "limit": 100
}
ListUsersOnFolderArgs
doc_idStringThe Paper doc ID.
limitInt32(min=1, max=1000)Size limit per batch. The maximum number of users that can be retrieved per batch is 1000. Higher value results in invalid arguments error. The default for this field is 1000.
Returns
{
    "cursor": {
        "expiration": "2016-08-07T14:56:15Z",
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb"
    },
    "has_more": false,
    "invitees": [
        {
            ".tag": "email",
            "email": "jessica@example.com"
        }
    ],
    "users": [
        {
            "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "display_name": "Robert Smith",
            "email": "bob@example.com",
            "same_team": true,
            "team_member_id": "dbmid:abcd1234"
        }
    ]
}
ListUsersOnFolderResponse
inviteesList of ()List of email addresses that are invited on the Paper folder.
usersList of ()List of users that are invited on the Paper folder.
cursorPass the cursor into docs/folder_users/list/continue to paginate through all users. The cursor preserves all properties as specified in the original call to docs/folder_users/list.
has_moreBooleanWill be set to True if a subsequent call with the provided cursor to docs/folder_users/list/continue returns immediately with some results. If set to False please allow some delay before making another call to docs/folder_users/list/continue.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
DocLookupError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
See also general errors.

/docs/folder_users/list/continue


"DEPRECATED"
Description

Once a cursor has been retrieved from docs/folder_users/list, use this to paginate through all users on the Paper folder. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/folder_users/list/continue
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/folder_users/list/continue \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd\",\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\"}"
Parameters
{
    "cursor": "U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd",
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
ListUsersOnFolderContinueArgs
doc_idStringThe Paper doc ID.
cursorStringThe cursor obtained from docs/folder_users/list or docs/folder_users/list/continue. Allows for pagination.
Returns
{
    "cursor": {
        "expiration": "2016-08-07T14:56:15Z",
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb"
    },
    "has_more": false,
    "invitees": [
        {
            ".tag": "email",
            "email": "jessica@example.com"
        }
    ],
    "users": [
        {
            "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "display_name": "Robert Smith",
            "email": "bob@example.com",
            "same_team": true,
            "team_member_id": "dbmid:abcd1234"
        }
    ]
}
ListUsersOnFolderResponse
inviteesList of ()List of email addresses that are invited on the Paper folder.
usersList of ()List of users that are invited on the Paper folder.
cursorPass the cursor into docs/folder_users/list/continue to paginate through all users. The cursor preserves all properties as specified in the original call to docs/folder_users/list.
has_moreBooleanWill be set to True if a subsequent call with the provided cursor to docs/folder_users/list/continue returns immediately with some results. If set to False please allow some delay before making another call to docs/folder_users/list/continue.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
ListUsersCursorError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
cursor_error
See also general errors.

/docs/get_folder_info


"DEPRECATED"
Description

Retrieves folder information for the given Paper doc. This includes: - folder sharing policy; permissions for subfolders are set by the top-level folder. - full 'filepath', i.e. the list of folders (both folderId and folderName) from the root folder to the folder directly containing the Paper doc. If the Paper doc is not in any folder (aka unfiled) the response will be empty. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/get_folder_info
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/get_folder_info \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
RefPaperDoc
doc_idStringThe Paper doc ID.
Returns
{
    "folder_sharing_policy_type": {
        ".tag": "team"
    },
    "folders": [
        {
            "id": "e.gGYT6HSafpMej9bUv306oGm60vrHiCHgEFnzziioPGCvHf",
            "name": "Design docs"
        }
    ]
}
FoldersContainingPaperDoc
Metadata about Paper folders containing the specififed Paper doc.
folder_sharing_policy_type?The sharing policy of the folder containing the Paper doc. This field is optional.
foldersList of ()?The folder path. If present the first folder is the root folder. This field is optional.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
DocLookupError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
See also general errors.

/docs/list


"DEPRECATED"
Description

Return the list of all Paper docs according to the argument specifications. To iterate over through the full pagination, pass the cursor to docs/list/continue. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/list
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/list \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"filter_by\":\"docs_created\",\"limit\":100,\"sort_by\":\"modified\",\"sort_order\":\"descending\",\"stop_at_date\":\"2024-10-11T12:34:55Z\"}"
Parameters
{
    "filter_by": "docs_created",
    "limit": 100,
    "sort_by": "modified",
    "sort_order": "descending",
    "stop_at_date": "2024-10-11T12:34:55Z"
}
ListPaperDocsArgs
filter_byAllows user to specify how the Paper docs should be filtered. The default for this union is docs_accessed.
sort_byAllows user to specify how the Paper docs should be sorted. The default for this union is accessed.
sort_orderAllows user to specify the sort order of the result. The default for this union is ascending.
limitInt32(min=1, max=1000)Size limit per batch. The maximum number of docs that can be retrieved per batch is 1000. Higher value results in invalid arguments error. The default for this field is 1000.
stop_at_date Timestamp(format="%Y-%m-%dT%H:%M:%SZ")?Do not return results beyond this date. Behavior depends on sort order. This field is optional.
Returns
{
    "cursor": {
        "expiration": "2016-08-07T14:56:15Z",
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb"
    },
    "doc_ids": [
        "zO1E7coc54sE8IuMdUoxz",
        "mm1AmDgVyZ10zf7qb0qzn",
        "dByYHZvTPBnXilGgyc5mm"
    ],
    "has_more": true
}
ListPaperDocsResponse
doc_ids List of (String)The list of Paper doc IDs that can be used to access the given Paper docs or supplied to other API methods. The list is sorted in the order specified by the initial call to docs/list.
cursorPass the cursor into docs/list/continue to paginate through all files. The cursor preserves all properties as specified in the original call to docs/list.
has_moreBooleanWill be set to True if a subsequent call with the provided cursor to docs/list/continue returns immediately with some results. If set to False please allow some delay before making another call to docs/list/continue.
Errors
No endpoint-specific errors.
See also general errors.

/docs/list/continue


"DEPRECATED"
Description

Once a cursor has been retrieved from docs/list, use this to paginate through all Paper doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/list/continue
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.metadata.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/list/continue \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd\"}"
Parameters
{
    "cursor": "U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd"
}
ListPaperDocsContinueArgs
cursorStringThe cursor obtained from docs/list or docs/list/continue. Allows for pagination.
Returns
{
    "cursor": {
        "expiration": "2016-08-07T14:56:15Z",
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb"
    },
    "doc_ids": [
        "zO1E7coc54sE8IuMdUoxz",
        "mm1AmDgVyZ10zf7qb0qzn",
        "dByYHZvTPBnXilGgyc5mm"
    ],
    "has_more": true
}
ListPaperDocsResponse
doc_ids List of (String)The list of Paper doc IDs that can be used to access the given Paper docs or supplied to other API methods. The list is sorted in the order specified by the initial call to docs/list.
cursorPass the cursor into docs/list/continue to paginate through all files. The cursor preserves all properties as specified in the original call to docs/list.
has_moreBooleanWill be set to True if a subsequent call with the provided cursor to docs/list/continue returns immediately with some results. If set to False please allow some delay before making another call to docs/list/continue.
Errors
ListDocsCursorError (open union)
cursor_error
See also general errors.

/docs/permanently_delete


"DEPRECATED"
Description

Permanently deletes the given Paper doc. This operation is final as the doc cannot be recovered. This action can be performed only by the doc owner. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/permanently_delete
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.permanent_delete
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/permanently_delete \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
RefPaperDoc
doc_idStringThe Paper doc ID.
Returns
No return values.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
DocLookupError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
See also general errors.

/docs/sharing_policy/get


"DEPRECATED"
Description

Gets the default sharing policy for the given Paper doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/sharing_policy/get
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/sharing_policy/get \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
RefPaperDoc
doc_idStringThe Paper doc ID.
Returns
{
    "public_sharing_policy": {
        ".tag": "people_with_link_can_edit"
    },
    "team_sharing_policy": {
        ".tag": "people_with_link_can_edit"
    }
}
SharingPolicy
Sharing policy of Paper doc.
public_sharing_policy?This value applies to the non-team members. This field is optional.
team_sharing_policy?This value applies to the team members only. The value is null for all personal accounts. This field is optional.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
DocLookupError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
See also general errors.

/docs/sharing_policy/set


"DEPRECATED"
Description

Sets the default sharing policy for the given Paper doc. The default 'team_sharing_policy' can be changed only by teams, omit this field for personal accounts. The 'public_sharing_policy' policy can't be set to the value 'disabled' because this setting can be changed only via the team admin console. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/sharing_policy/set
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/sharing_policy/set \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\",\"sharing_policy\":{\"public_sharing_policy\":\"people_with_link_can_edit\",\"team_sharing_policy\":\"people_with_link_can_edit\"}}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "sharing_policy": {
        "public_sharing_policy": "people_with_link_can_edit",
        "team_sharing_policy": "people_with_link_can_edit"
    }
}
PaperDocSharingPolicy
doc_idStringThe Paper doc ID.
sharing_policyThe default sharing policy to be set for the Paper doc.
Returns
No return values.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
DocLookupError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
See also general errors.

/docs/update


"DEPRECATED"
Description

Updates an existing Paper doc with the provided content. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. This endpoint will be retired in September 2020. Refer to the Paper Migration Guide for more information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/update
Authentication
User Authentication
Endpoint format
Content-upload
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/update \
    --header "Authorization: Bearer <get access token>" \
    --header "Dropbox-API-Arg: {\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\",\"doc_update_policy\":\"overwrite_all\",\"import_format\":\"html\",\"revision\":12345}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
Example: Overwrite the doc content with provided content.
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "doc_update_policy": "overwrite_all",
    "import_format": "html",
    "revision": 12345
}
Example: Prepend the content into the doc (the doc title will remain unchanged).
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "doc_update_policy": "prepend",
    "import_format": "plain_text",
    "revision": 56556
}
PaperDocUpdateArgs
doc_idStringThe Paper doc ID.
doc_update_policyThe policy used for the current update call.
revisionInt64The latest doc revision. This value must match the head revision or an error code will be returned. This is to prevent colliding writes.
import_formatThe format of provided data.
Returns
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "revision": 456736745,
    "title": "Week one retention"
}
PaperDocCreateUpdateResult
doc_idStringDoc ID of the newly created doc.
revisionInt64The Paper doc revision. Simply an ever increasing number.
titleStringThe Paper doc title.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
Example: content_malformed
{
    "error": {
        ".tag": "content_malformed"
    },
    "error_summary": "content_malformed/..."
}
Example: revision_mismatch
{
    "error": {
        ".tag": "revision_mismatch"
    },
    "error_summary": "revision_mismatch/..."
}
Example: doc_length_exceeded
{
    "error": {
        ".tag": "doc_length_exceeded"
    },
    "error_summary": "doc_length_exceeded/..."
}
Example: image_size_exceeded
{
    "error": {
        ".tag": "image_size_exceeded"
    },
    "error_summary": "image_size_exceeded/..."
}
Example: doc_archived
{
    "error": {
        ".tag": "doc_archived"
    },
    "error_summary": "doc_archived/..."
}
Example: doc_deleted
{
    "error": {
        ".tag": "doc_deleted"
    },
    "error_summary": "doc_deleted/..."
}
PaperDocUpdateError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
content_malformedVoidThe provided content was malformed and cannot be imported to Paper.
revision_mismatchVoidThe provided revision does not match the document head.
doc_length_exceededVoidThe newly created Paper doc would be too large, split the content into multiple docs.
image_size_exceededVoidThe imported document contains an image that is too large. The current limit is 1MB. This only applies to HTML with data URI.
doc_archivedVoidThis operation is not allowed on archived Paper docs.
doc_deletedVoidThis operation is not allowed on deleted Paper docs.
See also general errors.

/docs/users/add


"DEPRECATED"
Description

Allows an owner or editor to add users to a Paper doc or change their permissions using their email address or Dropbox account ID. The doc owner's permissions cannot be changed. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/users/add
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/users/add \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"custom_message\":\"Welcome to Paper.\",\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\",\"members\":[{\"member\":{\".tag\":\"email\",\"email\":\"justin@example.com\"},\"permission_level\":\"view_and_comment\"}],\"quiet\":false}"
Parameters
{
    "custom_message": "Welcome to Paper.",
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "members": [
        {
            "member": {
                ".tag": "email",
                "email": "justin@example.com"
            },
            "permission_level": "view_and_comment"
        }
    ],
    "quiet": false
}
AddPaperDocUser
doc_idStringThe Paper doc ID.
membersList of (, max_items=20)User which should be added to the Paper doc. Specify only email address or Dropbox account ID.
custom_message String?A personal message that will be emailed to each successfully added member. This field is optional.
quietBooleanClients should set this to true if no email message shall be sent to added users. The default for this field is False.
Returns
List of (AddPaperDocUserMemberResult)
Per-member result for docs/users/add.
memberOne of specified input members.
resultThe outcome of the action on this member.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
DocLookupError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
See also general errors.

/docs/users/list


"DEPRECATED"
Description

Lists all users who visited the Paper doc or users with explicit access. This call excludes users who have been removed. The list is sorted by the date of the visit or the share date. The list will include both users, the explicitly shared ones as well as those who came in using the Paper url link. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/users/list
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/users/list \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\",\"filter_by\":\"shared\",\"limit\":100}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "filter_by": "shared",
    "limit": 100
}
ListUsersOnPaperDocArgs
doc_idStringThe Paper doc ID.
limitInt32(min=1, max=1000)Size limit per batch. The maximum number of users that can be retrieved per batch is 1000. Higher value results in invalid arguments error. The default for this field is 1000.
filter_bySpecify this attribute if you want to obtain users that have already accessed the Paper doc. The default for this union is shared.
Returns
{
    "cursor": {
        "expiration": "2016-08-07T14:56:15Z",
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb"
    },
    "doc_owner": {
        "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "display_name": "Robert Smith",
        "email": "bob@example.com",
        "same_team": true,
        "team_member_id": "dbmid:abcd1234"
    },
    "has_more": false,
    "invitees": [
        {
            "invitee": {
                ".tag": "email",
                "email": "jessica@example.com"
            },
            "permission_level": {
                ".tag": "edit"
            }
        }
    ],
    "users": [
        {
            "permission_level": {
                ".tag": "view_and_comment"
            },
            "user": {
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "display_name": "Robert Smith",
                "email": "bob@example.com",
                "same_team": true,
                "team_member_id": "dbmid:abcd1234"
            }
        }
    ]
}
ListUsersOnPaperDocResponse
inviteesList of ()List of email addresses with their respective permission levels that are invited on the Paper doc.
usersList of ()List of users with their respective permission levels that are invited on the Paper folder.
doc_ownerThe Paper doc owner. This field is populated on every single response.
cursorPass the cursor into docs/users/list/continue to paginate through all users. The cursor preserves all properties as specified in the original call to docs/users/list.
has_moreBooleanWill be set to True if a subsequent call with the provided cursor to docs/users/list/continue returns immediately with some results. If set to False please allow some delay before making another call to docs/users/list/continue.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
DocLookupError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
See also general errors.

/docs/users/list/continue


"DEPRECATED"
Description

Once a cursor has been retrieved from docs/users/list, use this to paginate through all users on the Paper doc. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/users/list/continue
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/users/list/continue \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"cursor\":\"U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd\",\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\"}"
Parameters
{
    "cursor": "U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd",
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
ListUsersOnPaperDocContinueArgs
doc_idStringThe Paper doc ID.
cursorStringThe cursor obtained from docs/users/list or docs/users/list/continue. Allows for pagination.
Returns
{
    "cursor": {
        "expiration": "2016-08-07T14:56:15Z",
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb"
    },
    "doc_owner": {
        "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "display_name": "Robert Smith",
        "email": "bob@example.com",
        "same_team": true,
        "team_member_id": "dbmid:abcd1234"
    },
    "has_more": false,
    "invitees": [
        {
            "invitee": {
                ".tag": "email",
                "email": "jessica@example.com"
            },
            "permission_level": {
                ".tag": "edit"
            }
        }
    ],
    "users": [
        {
            "permission_level": {
                ".tag": "view_and_comment"
            },
            "user": {
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "display_name": "Robert Smith",
                "email": "bob@example.com",
                "same_team": true,
                "team_member_id": "dbmid:abcd1234"
            }
        }
    ]
}
ListUsersOnPaperDocResponse
inviteesList of ()List of email addresses with their respective permission levels that are invited on the Paper doc.
usersList of ()List of users with their respective permission levels that are invited on the Paper folder.
doc_ownerThe Paper doc owner. This field is populated on every single response.
cursorPass the cursor into docs/users/list/continue to paginate through all users. The cursor preserves all properties as specified in the original call to docs/users/list.
has_moreBooleanWill be set to True if a subsequent call with the provided cursor to docs/users/list/continue returns immediately with some results. If set to False please allow some delay before making another call to docs/users/list/continue.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
ListUsersCursorError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
cursor_error
See also general errors.

/docs/users/remove


"DEPRECATED"
Description

Allows an owner or editor to remove users from a Paper doc using their email address or Dropbox account ID. The doc owner cannot be removed. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/docs/users/remove
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/users/remove \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\":\"uaSvRuxvnkFa12PTkBv5q\",\"member\":{\".tag\":\"email\",\"email\":\"justin@example.com\"}}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "member": {
        ".tag": "email",
        "email": "justin@example.com"
    }
}
RemovePaperDocUser
doc_idStringThe Paper doc ID.
memberUser which should be removed from the Paper doc. Specify only email address or Dropbox account ID.
Returns
No return values.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: doc_not_found
{
    "error": {
        ".tag": "doc_not_found"
    },
    "error_summary": "doc_not_found/..."
}
DocLookupError (union)
insufficient_permissionsVoidYour 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_foundVoidThe required doc was not found.
See also general errors.

/folders/create


"DEPRECATED"
Description

Create a new Paper folder with the provided info. Note that this endpoint will continue to work for content created by users on the older version of Paper. To check which version of Paper a user is on, use /users/features/get_values. If the paper_as_files feature is enabled, then the user is running the new version of Paper. Refer to the Paper Migration Guide for migration information.

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

URL Structure
https://api.dropboxapi.com/2/paper/folders/create
Authentication
User Authentication
Endpoint format
RPC
Required Scope
files.content.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/folders/create \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"name\":\"my new folder\"}"
Parameters
Example: Create a top-level private folder.
{
    "name": "my new folder"
}
Example: Create a top-level team folder.
{
    "is_team_folder": true,
    "name": "my new folder"
}
Example: Create a new Paper folder inside an existing folder. The new folder will be a private or team folder depending on its parent.
{
    "name": "my new folder",
    "parent_folder_id": "e.gGYT6HSafpMej9bUv306GarglI7GGeAM3yvfZvXHO9u4mV"
}
PaperFolderCreateArg
nameStringThe name of the new Paper folder.
parent_folder_id String?The encrypted Paper folder Id where the new Paper folder should be created. The API user has to have write access to this folder or error is thrown. If not supplied, the new folder will be created at top level. This field is optional.
is_team_folder Boolean?Whether the folder to be created should be a team folder. This value will be ignored if parent_folder_id is supplied, as the new folder will inherit the type (private or team folder) from its parent. We will by default create a top-level private folder if both parent_folder_id and is_team_folder are not supplied. This field is optional.
Returns
{
    "folder_id": "abcd"
}
PaperFolderCreateResult
folder_idStringFolder ID of the newly created folder.
Errors
Example: insufficient_permissions
{
    "error": {
        ".tag": "insufficient_permissions"
    },
    "error_summary": "insufficient_permissions/..."
}
Example: other
{
    "error": {
        ".tag": "other"
    },
    "error_summary": "other/..."
}
Example: folder_not_found
{
    "error": {
        ".tag": "folder_not_found"
    },
    "error_summary": "folder_not_found/..."
}
Example: invalid_folder_id
{
    "error": {
        ".tag": "invalid_folder_id"
    },
    "error_summary": "invalid_folder_id/..."
}
PaperFolderCreateError (union)
insufficient_permissionsVoidYour 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.
folder_not_foundVoidThe specified parent Paper folder cannot be found.
invalid_folder_idVoidThe folder id cannot be decrypted to valid folder id.
See also general errors.

Deprecated: sharing

Deprecated endpoints for sharing

/create_shared_link


Description

Create a shared link. If a shared link already exists for the given path, that link is returned. Previously, it was technically possible to break a shared link by moving or renaming the corresponding file or folder. In the future, this will no longer be the case, so your app shouldn't rely on this behavior. Instead, if your app needs to revoke a shared link, use revoke_shared_link.

URL Structure
https://api.dropboxapi.com/2/sharing/create_shared_link
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/create_shared_link \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"/Homework/Math/Prime_Numbers.txt\",\"short_url\":false}"
Parameters
{
    "path": "/Homework/Math/Prime_Numbers.txt",
    "short_url": false
}
CreateSharedLinkArg
pathStringThe path to share.
short_urldeprecatedBooleanField is deprecated. None The default for this field is False.
pending_upload?If it's okay to share a path that does not yet exist, set this to either PendingUploadMode.file or PendingUploadMode.folder to indicate whether to assume it's a file or folder. This field is optional.
Returns
{
    "path": "/Homework/Math/Prime_Numbers.txt",
    "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0",
    "visibility": {
        ".tag": "public"
    }
}
PathLinkMetadata
Metadata for a path-based shared link.
urlStringURL of the shared link.
visibilityWho can access the link.
pathStringPath in user's Dropbox.
expires Timestamp(format="%Y-%m-%dT%H:%M:%SZ")?Expiration time, if set. By default the link won't expire. This field is optional.
Errors
CreateSharedLinkError (open union)
path
See also general errors.

/get_shared_links


DEPRECATED BY /list_shared_links
Description

Returns a list of LinkMetadata objects for this user, including collection links. If no path is given, returns a list of all shared links for the current user, including collection links, up to a maximum of 1000 links. If a non-empty path is given, returns a list of all shared links that allow access to the given path. Collection links are never returned in this case.

URL Structure
https://api.dropboxapi.com/2/sharing/get_shared_links
Authentication
User Authentication
Endpoint format
RPC
Required Scope
sharing.read
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/get_shared_links \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\":\"\"}"
Parameters
Example: Get all links, including collection links.
{
    "path": ""
}
Example: Get links giving access to /Homework/Math.
{
    "path": "/Homework/Math"
}
GetSharedLinksArg
path String?See get_shared_links description. This field is optional.
Returns
{
    "links": [
        {
            ".tag": "path",
            "path": "/Homework/Math/Prime_Numbers.txt",
            "url": "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0",
            "visibility": {
                ".tag": "public"
            }
        }
    ]
}
GetSharedLinksResult
linksList of ()Shared links applicable to the path argument.
Errors
GetSharedLinksError (open union)
path String? This field is optional.
See also general errors.

/remove_file_member


DEPRECATED BY /remove_file_member_2
Description

Identical to remove_file_member_2 but with less information returned.

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

URL Structure
https://api.dropboxapi.com/2/sharing/remove_file_member
Authentication
User Authentication, Dropbox-API-Select-Admin (Team Admin)
Endpoint format
RPC
Required Scope
sharing.write
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/remove_file_member \
    --header "Authorization: Bearer <get access token>" \
    --header "Content-Type: application/json" \
    --data "{\"file\":\"id:3kmLmQFnf1AAAAAAAAAAAw\",\"member\":{\".tag\":\"email\",\"email\":\"justin@example.com\"}}"
Parameters
{
    "file": "id:3kmLmQFnf1AAAAAAAAAAAw",
    "member": {
        ".tag": "email",
        "email": "justin@example.com"
    }
}
RemoveFileMemberArg
Arguments for remove_file_member_2.
fileString(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?")File from which to remove members.
memberMember to remove from this file. Note that even if an email is specified, it may result in the removal of a user (not an invitee) if the user's main account corresponds to that email address.
Returns
{
    ".tag": "success"
}
FileMemberActionIndividualResult (union)
success?Part of the response for both add_file_member and remove_file_member_v1 (deprecated). For add_file_member, indicates giving access was successful and at what AccessLevel. For remove_file_member_v1, indicates member was successfully removed from the file. If AccessLevel is given, the member still has access via a parent shared folder. This field is optional.
member_errorUser was not able to perform this action.
Errors
RemoveFileMemberError (open union)
Errors for remove_file_member_2.
user_error
access_error
no_explicit_accessThis member does not have explicit access to the file and therefore cannot be removed. The return value is the access that a user might have to the file from a parent folder.
See also general errors.