Dropbox for HTTP Developers

auth

file_properties

file_requests

files

paper

sharing

Dropbox API v2

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

Request and response formats

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

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

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

RPC endpoints

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

Content-upload endpoints

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

Content-download endpoints

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

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

Browser-based JavaScript and CORS pre-flight requests

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

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

Date format

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

2015-05-15T15:50:38Z

Path formats

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

Every file and folder in Dropbox also has an ID (e.g. "id:abc123xyz") that can be obtained from any endpoint that returns metadata. Some endpoints, as noted in the individual endpoint documentation below, can accept IDs in addition to normal paths. A path relative to a folder's ID can be constructed by using a slash (e.g. "id:abc123xyz/hello.txt").

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

Case insensitivity

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

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

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

Authorization

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

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

/oauth2/authorize

Description

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

OAuth 2.0 supports two authorization flows:

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

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

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

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

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

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

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

Code flow

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

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

Sample response

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

Token flow

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

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

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

Sample response

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

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

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

/oauth2/token

Description

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

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

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

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

Sample response

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

Errors

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

Errors by status code

CodeDescription
400Bad input parameter. The response body is a plaintext message with more information.
401Bad or expired token. This can happen if the access token is expired or if the access token has been revoked by Dropbox or the user. To fix this, you should re-authenticate the user.
The Content-Type of the response is JSON of typeAuthError
Example: invalid_access_token
{
    "error_summary": "invalid_access_token/...",
    "error": {
        ".tag": "invalid_access_token"
    }
}
Example: invalid_select_user
{
    "error_summary": "invalid_select_user/...",
    "error": {
        ".tag": "invalid_select_user"
    }
}
Example: invalid_select_admin
{
    "error_summary": "invalid_select_admin/...",
    "error": {
        ".tag": "invalid_select_admin"
    }
}
Example: user_suspended
{
    "error_summary": "user_suspended/...",
    "error": {
        ".tag": "user_suspended"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
AuthError (open union)
Errors occurred during authentication. This datatype comes from an imported namespace originally defined in the auth namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_access_token Void The access token is invalid.
invalid_select_user Void The user specified in 'Dropbox-API-Select-User' is no longer on the team.
invalid_select_admin Void The user specified in 'Dropbox-API-Select-Admin' is not a Dropbox Business team admin.
user_suspended Void The user has been suspended.
409Endpoint-specific error. Look to the JSON response body for the specifics of the error.
429Your app is making too many requests for the given user or team and is being rate limited. Your app should wait for the number of seconds specified in the "Retry-After" response header before trying again.
The Content-Type of the response can be JSON or plaintext. If it is JSON, it will be typeRateLimitErrorYou can find more information in the data ingress guide.
RateLimitError
Error occurred because the app is being rate limited. This datatype comes from an imported namespace originally defined in the auth namespace.
reason RateLimitReason The reason why the app is being rate limited.
RateLimitReason (open union)
This datatype comes from an imported namespace originally defined in the auth namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
too_many_requests Void You are making too many requests in the past few minutes.
too_many_write_operations Void There are currently too many write operations happening in the user's Dropbox.
retry_after UInt64 The number of seconds that the app should wait before making another request. The default for this field is 1.
5xxAn error occurred on the Dropbox servers. Check status.dropbox.com for announcements about Dropbox service issues.

Endpoint-specific errors (409)

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

Generate access token

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

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

auth

/token/from_oauth1

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
Example
Get app key and secret for:
curl -X POST https://api.dropboxapi.com/2/auth/token/from_oauth1 \
    --header "Authorization: Basic " \
    --header "Content-Type: application/json" \
    --data "{\"oauth1_token\": \"qievr8hamyg6ndck\",\"oauth1_token_secret\": \"qomoftv0472git7\"}"
Parameters
{
    "oauth1_token": "qievr8hamyg6ndck",
    "oauth1_token_secret": "qomoftv0472git7"
}
TokenFromOAuth1Arg
oauth1_token String(min_length=1) The supplied OAuth 1.0 access token.
oauth1_token_secret String(min_length=1) The token secret associated with the supplied access token.
Returns
{
    "oauth2_token": "9mCrkS7BIdAAAAAAAAAAHHS0TsSnpYvKQVtKdBnN5IuzhYOGblSgTcHgBFKFMmFn"
}
TokenFromOAuth1Result
oauth2_token String(min_length=1) The OAuth 2.0 token generated from the supplied OAuth 1.0 token.
Errors
Example: invalid_oauth1_token_info
{
    "error_summary": "invalid_oauth1_token_info/...",
    "error": {
        ".tag": "invalid_oauth1_token_info"
    }
}
Example: app_id_mismatch
{
    "error_summary": "app_id_mismatch/...",
    "error": {
        ".tag": "app_id_mismatch"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
TokenFromOAuth1Error (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_oauth1_token_info Void Part or all of the OAuth 1.0 access token info is invalid.
app_id_mismatch Void The authorized app does not match the app associated with the supplied access token.

/token/revoke

Description

Disables the access token used to authenticate the call.

URL Structure
https://api.dropboxapi.com/2/auth/token/revoke
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/auth/token/revoke \
    --header "Authorization: Bearer "
Parameters

No parameters.

Returns

No return values.

Errors

No 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 PropertyField. These fields encapsulate the actual key/value data.

Fields are added to a Dropbox file using a PropertyGroup. Property groups contain a reference to a Dropbox file and a PropertyGroupTemplate. Property groups are uniquely identified by the combination of their associated Dropbox file and template.

The 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 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 template/*_for_user endpoints, while team-owned templates are accessed via the team-auth template/*_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.

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/add
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/add \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/my_awesome/word.docx\",\"property_groups\": [{\"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\",\"fields\": [{\"name\": \"Security Policy\",\"value\": \"Confidential\"}]}]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ]
}
AddPropertiesArg
path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file or folder.
property_groups List of (PropertyGroup) The property groups which are to be added to a Dropbox file.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
Returns

No return values.

Errors
Example: restricted_content
{
    "error_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: unsupported_folder
{
    "error_summary": "unsupported_folder/...",
    "error": {
        ".tag": "unsupported_folder"
    }
}
Example: property_field_too_large
{
    "error_summary": "property_field_too_large/...",
    "error": {
        ".tag": "property_field_too_large"
    }
}
Example: does_not_fit_template
{
    "error_summary": "does_not_fit_template/...",
    "error": {
        ".tag": "does_not_fit_template"
    }
}
Example: property_group_already_exists
{
    "error_summary": "property_group_already_exists/...",
    "error": {
        ".tag": "property_group_already_exists"
    }
}
AddPropertiesError (union)
The value will be one of the following datatypes:
template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.
restricted_content Void You do not have permission to modify this template.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
unsupported_folder Void This folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_field_too_large Void One or more of the supplied property field values is too large.
does_not_fit_template Void One or more of the supplied property fields does not conform to the template specifications.
property_group_already_exists Void A property group associated with this template and file already exists.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/overwrite
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/overwrite \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/my_awesome/word.docx\",\"property_groups\": [{\"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\",\"fields\": [{\"name\": \"Security Policy\",\"value\": \"Confidential\"}]}]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ]
}
OverwritePropertyGroupArg
path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file or folder.
property_groups List of (PropertyGroup, min_items=1) The property groups "snapshot" updates to force apply.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
Returns

No return values.

Errors
Example: restricted_content
{
    "error_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: unsupported_folder
{
    "error_summary": "unsupported_folder/...",
    "error": {
        ".tag": "unsupported_folder"
    }
}
Example: property_field_too_large
{
    "error_summary": "property_field_too_large/...",
    "error": {
        ".tag": "property_field_too_large"
    }
}
Example: does_not_fit_template
{
    "error_summary": "does_not_fit_template/...",
    "error": {
        ".tag": "does_not_fit_template"
    }
}
InvalidPropertyGroupError (union)
The value will be one of the following datatypes:
template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.
restricted_content Void You do not have permission to modify this template.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
unsupported_folder Void This folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_field_too_large Void One or more of the supplied property field values is too large.
does_not_fit_template Void One or more of the supplied property fields does not conform to the template specifications.

/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. Templates can't be removed once created.

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/remove
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/remove \
    --header "Authorization: Bearer " \
    --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
path String(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_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: unsupported_folder
{
    "error_summary": "unsupported_folder/...",
    "error": {
        ".tag": "unsupported_folder"
    }
}
RemovePropertiesError (union)
The value will be one of the following datatypes:
template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.
restricted_content Void You do not have permission to modify this template.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
unsupported_folder Void This folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_group_lookup LookUpPropertiesError
LookUpPropertiesError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
property_group_not_found Void No property group was found.

/properties/search/continue

Description

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

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/search/continue
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/search/continue \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"cursor\": \"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
PropertiesSearchContinueArg
cursor String(min_length=1) The cursor returned by your last call to properties/search or properties/search/continue.
Returns
{
    "matches": [
        {
            "id": "id:a4ayc_80_OEAAAAAAAAAXz",
            "path": "/my_awesome/word.docx",
            "is_deleted": false,
            "property_groups": [
                {
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ]
                }
            ]
        }
    ]
}
PropertiesSearchResult
matches List of (PropertiesSearchMatch) A list (possibly empty) of matches for the query.
PropertiesSearchMatch
id String(min_length=1) The ID for the matched file or folder.
path String The path for the matched file or folder.
is_deleted Boolean Whether the file or folder is deleted.
property_groups List of (PropertyGroup) List of custom property groups associated with the file.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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_summary": "reset/...",
    "error": {
        ".tag": "reset"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
PropertiesSearchContinueError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
reset Void Indicates that the cursor has been invalidated. Call properties/search to obtain a new cursor.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/properties/update
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/properties/update \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/my_awesome/word.docx\",\"update_property_groups\": [{\"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\",\"add_or_update_fields\": [{\"name\": \"Security Policy\",\"value\": \"Confidential\"}],\"remove_fields\": []}]}"
Parameters
{
    "path": "/my_awesome/word.docx",
    "update_property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "add_or_update_fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ],
            "remove_fields": []
        }
    ]
}
UpdatePropertiesArg
path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file or folder.
update_property_groups List of (PropertyGroupUpdate) The property groups "delta" updates to apply.
PropertyGroupUpdate
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template.
add_or_update_fields List of (PropertyField)? Property fields to update. If the property field already exists, it is updated. If the property field doesn't exist, the property group is added. This field is optional.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
remove_fields List of (String)? Property fields to remove (by name), provided they exist. This field is optional.
Returns

No return values.

Errors
Example: restricted_content
{
    "error_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: unsupported_folder
{
    "error_summary": "unsupported_folder/...",
    "error": {
        ".tag": "unsupported_folder"
    }
}
Example: property_field_too_large
{
    "error_summary": "property_field_too_large/...",
    "error": {
        ".tag": "property_field_too_large"
    }
}
Example: does_not_fit_template
{
    "error_summary": "does_not_fit_template/...",
    "error": {
        ".tag": "does_not_fit_template"
    }
}
UpdatePropertiesError (union)
The value will be one of the following datatypes:
template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.
restricted_content Void You do not have permission to modify this template.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
unsupported_folder Void This folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_field_too_large Void One or more of the supplied property field values is too large.
does_not_fit_template Void One or more of the supplied property fields does not conform to the template specifications.
property_group_lookup LookUpPropertiesError
LookUpPropertiesError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
property_group_not_found Void No property group was found.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/templates/add_for_user
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/templates/add_for_user \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"name\": \"Security\",\"description\": \"These properties describe how confidential this file or folder is.\",\"fields\": [{\"name\": \"Security Policy\",\"description\": \"This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.\",\"type\": \"string\"}]}"
Parameters
{
    "name": "Security",
    "description": "These properties describe how confidential this file or folder is.",
    "fields": [
        {
            "name": "Security Policy",
            "description": "This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.",
            "type": "string"
        }
    ]
}
AddTemplateArg
name String Display name for the template. Template names can be up to 256 bytes.
description String Description for the template. Template descriptions can be up to 1024 bytes.
fields List of (PropertyFieldTemplate) Definitions of the property fields associated with this template. There can be up to 32 properties in a single template.
PropertyFieldTemplate
Defines how a single property field may be structured. Used exclusively by PropertyGroupTemplate.
name String Key of the property field being described. Property field keys can be up to 256 bytes.
description String Description of the property field. Property field descriptions can be up to 1024 bytes.
type PropertyType Data type of the value of this property field. This type will be enforced upon property creation and modifications.
PropertyType (open union)
Data type of the given property field added. The value will be one of the following datatypes. New values may be introduced as our API evolves.
string Void The associated property field will be of type string. Unicode is supported.
Returns
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
AddTemplateResult
template_id String(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_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: conflicting_property_names
{
    "error_summary": "conflicting_property_names/...",
    "error": {
        ".tag": "conflicting_property_names"
    }
}
Example: too_many_properties
{
    "error_summary": "too_many_properties/...",
    "error": {
        ".tag": "too_many_properties"
    }
}
Example: too_many_templates
{
    "error_summary": "too_many_templates/...",
    "error": {
        ".tag": "too_many_templates"
    }
}
Example: template_attribute_too_large
{
    "error_summary": "template_attribute_too_large/...",
    "error": {
        ".tag": "template_attribute_too_large"
    }
}
ModifyTemplateError (union)
The value will be one of the following datatypes:
template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.
restricted_content Void You do not have permission to modify this template.
conflicting_property_names Void A property field key with that name already exists in the template.
too_many_properties Void There are too many properties in the changed template. The maximum number of properties per template is 32.
too_many_templates Void There are too many templates for the team.
template_attribute_too_large Void The template name, description or one or more of the property field keys is too large.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/templates/get_for_user
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/templates/get_for_user \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}"
Parameters
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
GetTemplateArg
template_id String(min_length=1, pattern="(/|ptid:).*") An identifier for template added by route See templates/add_for_user or templates/add_for_team.
Returns
{
    "name": "Security",
    "description": "These properties describe how confidential this file or folder is.",
    "fields": [
        {
            "name": "Security Policy",
            "description": "This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.",
            "type": {
                ".tag": "string"
            }
        }
    ]
}
GetTemplateResult
name String Display name for the template. Template names can be up to 256 bytes.
description String Description for the template. Template descriptions can be up to 1024 bytes.
fields List of (PropertyFieldTemplate) Definitions of the property fields associated with this template. There can be up to 32 properties in a single template.
PropertyFieldTemplate
Defines how a single property field may be structured. Used exclusively by PropertyGroupTemplate.
name String Key of the property field being described. Property field keys can be up to 256 bytes.
description String Description of the property field. Property field descriptions can be up to 1024 bytes.
type PropertyType Data type of the value of this property field. This type will be enforced upon property creation and modifications.
PropertyType (open union)
Data type of the given property field added. The value will be one of the following datatypes. New values may be introduced as our API evolves.
string Void The associated property field will be of type string. Unicode is supported.
Errors
Example: restricted_content
{
    "error_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
TemplateError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.
restricted_content Void You do not have permission to modify this template.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/templates/list_for_user
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/templates/list_for_user \
    --header "Authorization: Bearer "
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_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
TemplateError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.
restricted_content Void You do not have permission to modify this template.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/templates/remove_for_user
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/templates/remove_for_user \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}"
Parameters
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
RemoveTemplateArg
template_id String(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_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
TemplateError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.
restricted_content Void You do not have permission to modify this template.

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

URL Structure
https://api.dropboxapi.com/2/file_properties/templates/update_for_user
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_properties/templates/update_for_user \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\",\"name\": \"New Security Template Name\",\"description\": \"These properties will describe how confidential this file or folder is.\",\"add_fields\": [{\"name\": \"Security Policy\",\"description\": \"This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.\",\"type\": \"string\"}]}"
Parameters
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
    "name": "New Security Template Name",
    "description": "These properties will describe how confidential this file or folder is.",
    "add_fields": [
        {
            "name": "Security Policy",
            "description": "This is the security policy of the file or folder described.\nPolicies can be Confidential, Public or Internal.",
            "type": "string"
        }
    ]
}
UpdateTemplateArg
template_id String(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_fields List of (PropertyFieldTemplate)? 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.
PropertyFieldTemplate
Defines how a single property field may be structured. Used exclusively by PropertyGroupTemplate.
name String Key of the property field being described. Property field keys can be up to 256 bytes.
description String Description of the property field. Property field descriptions can be up to 1024 bytes.
type PropertyType Data type of the value of this property field. This type will be enforced upon property creation and modifications.
PropertyType (open union)
Data type of the given property field added. The value will be one of the following datatypes. New values may be introduced as our API evolves.
string Void The associated property field will be of type string. Unicode is supported.
Returns
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
UpdateTemplateResult
template_id String(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_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: conflicting_property_names
{
    "error_summary": "conflicting_property_names/...",
    "error": {
        ".tag": "conflicting_property_names"
    }
}
Example: too_many_properties
{
    "error_summary": "too_many_properties/...",
    "error": {
        ".tag": "too_many_properties"
    }
}
Example: too_many_templates
{
    "error_summary": "too_many_templates/...",
    "error": {
        ".tag": "too_many_templates"
    }
}
Example: template_attribute_too_large
{
    "error_summary": "template_attribute_too_large/...",
    "error": {
        ".tag": "template_attribute_too_large"
    }
}
ModifyTemplateError (union)
The value will be one of the following datatypes:
template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.
restricted_content Void You do not have permission to modify this template.
conflicting_property_names Void A property field key with that name already exists in the template.
too_many_properties Void There are too many properties in the changed template. The maximum number of properties per template is 32.
too_many_templates Void There are too many templates for the team.
template_attribute_too_large Void The template name, description or one or more of the property field keys is too large.

file_requests

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

/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
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/create \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"title\": \"Homework submission\",\"destination\": \"/File Requests/Homework\",\"deadline\": {\"deadline\": \"2020-10-12T17:00:00Z\",\"allow_late_uploads\": \"seven_days\"},\"open\": true}"
Parameters
{
    "title": "Homework submission",
    "destination": "/File Requests/Homework",
    "deadline": {
        "deadline": "2020-10-12T17:00:00Z",
        "allow_late_uploads": "seven_days"
    },
    "open": true
}
CreateFileRequestArgs
Arguments for create.
title String(min_length=1) The title of the file request. Must not be empty.
destination String(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 FileRequestDeadline? The deadline for the file request. Deadlines can only be set by Pro and Business accounts. This field is optional.
FileRequestDeadline
deadline Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The deadline for this file request.
allow_late_uploads GracePeriod? If set, allow uploads after the deadline has passed. These uploads will be marked overdue. This field is optional.
GracePeriod (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
one_day Void
two_days Void
seven_days Void
thirty_days Void
always Void
open Boolean Whether 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.
Returns
{
    "id": "oaCAVmEyrqYnkZX9955Y",
    "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y",
    "title": "Homework submission",
    "created": "2015-10-05T17:00:00Z",
    "is_open": true,
    "file_count": 3,
    "destination": "/File Requests/Homework",
    "deadline": {
        "deadline": "2020-10-12T17:00:00Z",
        "allow_late_uploads": {
            ".tag": "seven_days"
        }
    }
}
Example: with_deadline
{
    "id": "BAJ7IrRGicQKGToykQdB",
    "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB",
    "title": "Photo contest submission",
    "created": "2015-11-02T04:00:00Z",
    "is_open": true,
    "file_count": 105,
    "destination": "/Photo contest entries",
    "deadline": {
        "deadline": "2020-10-12T17:00:00Z"
    }
}
Example: with_no_deadline
{
    "id": "rxwMPvK3ATTa0VxOJu5T",
    "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T",
    "title": "Wedding photo submission",
    "created": "2015-12-15T13:02:00Z",
    "is_open": true,
    "file_count": 37,
    "destination": "/Wedding photos"
}
FileRequest
A file request for receiving files into the user's Dropbox account.
id String(min_length=1, pattern="[-_0-9a-zA-Z]+") The ID of the file request.
url String(min_length=1) The URL of the file request.
title String(min_length=1) The title of the file request.
created Timestamp(format="%Y-%m-%dT%H:%M:%SZ") When this file request was created.
is_open Boolean Whether or not the file request is open. If the file request is closed, it will not accept any more file submissions.
file_count Int64 The 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 FileRequestDeadline? The deadline for this file request. Only set if the request has a deadline. This field is optional.
FileRequestDeadline
deadline Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The deadline for this file request.
allow_late_uploads GracePeriod? If set, allow uploads after the deadline has passed. These uploads will be marked overdue. This field is optional.
GracePeriod (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
one_day Void
two_days Void
seven_days Void
thirty_days Void
always Void
Errors
Example: disabled_for_team
{
    "error_summary": "disabled_for_team/...",
    "error": {
        ".tag": "disabled_for_team"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: not_found
{
    "error_summary": "not_found/...",
    "error": {
        ".tag": "not_found"
    }
}
Example: not_a_folder
{
    "error_summary": "not_a_folder/...",
    "error": {
        ".tag": "not_a_folder"
    }
}
Example: app_lacks_access
{
    "error_summary": "app_lacks_access/...",
    "error": {
        ".tag": "app_lacks_access"
    }
}
Example: no_permission
{
    "error_summary": "no_permission/...",
    "error": {
        ".tag": "no_permission"
    }
}
Example: email_unverified
{
    "error_summary": "email_unverified/...",
    "error": {
        ".tag": "email_unverified"
    }
}
Example: validation_error
{
    "error_summary": "validation_error/...",
    "error": {
        ".tag": "validation_error"
    }
}
Example: invalid_location
{
    "error_summary": "invalid_location/...",
    "error": {
        ".tag": "invalid_location"
    }
}
Example: rate_limit
{
    "error_summary": "rate_limit/...",
    "error": {
        ".tag": "rate_limit"
    }
}
CreateFileRequestError (union)
There was an error creating the file request. The value will be one of the following datatypes:
disabled_for_team Void This user's Dropbox Business team doesn't allow file requests.
not_found Void This file request ID was not found.
not_a_folder Void The specified path is not a folder.
app_lacks_access Void This file request is not accessible to this app. Apps with the app folder permission can only access file requests in their app folder.
no_permission Void This user doesn't have permission to access or modify this file request.
email_unverified Void This 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_error Void There was an error validating the request. For example, the title was invalid, or there were disallowed characters in the destination path.
invalid_location Void File requests are not available on the specified folder.
rate_limit Void The user has reached the rate limit for creating file requests. The limit is currently 100 file requests per day.

/get

Description

Returns the specified file request.

URL Structure
https://api.dropboxapi.com/2/file_requests/get
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/get \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"id\": \"oaCAVmEyrqYnkZX9955Y\"}"
Parameters
{
    "id": "oaCAVmEyrqYnkZX9955Y"
}
GetFileRequestArgs
Arguments for get.
id String(min_length=1, pattern="[-_0-9a-zA-Z]+") The ID of the file request to retrieve.
Returns
{
    "id": "oaCAVmEyrqYnkZX9955Y",
    "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y",
    "title": "Homework submission",
    "created": "2015-10-05T17:00:00Z",
    "is_open": true,
    "file_count": 3,
    "destination": "/File Requests/Homework",
    "deadline": {
        "deadline": "2020-10-12T17:00:00Z",
        "allow_late_uploads": {
            ".tag": "seven_days"
        }
    }
}
Example: with_deadline
{
    "id": "BAJ7IrRGicQKGToykQdB",
    "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB",
    "title": "Photo contest submission",
    "created": "2015-11-02T04:00:00Z",
    "is_open": true,
    "file_count": 105,
    "destination": "/Photo contest entries",
    "deadline": {
        "deadline": "2020-10-12T17:00:00Z"
    }
}
Example: with_no_deadline
{
    "id": "rxwMPvK3ATTa0VxOJu5T",
    "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T",
    "title": "Wedding photo submission",
    "created": "2015-12-15T13:02:00Z",
    "is_open": true,
    "file_count": 37,
    "destination": "/Wedding photos"
}
FileRequest
A file request for receiving files into the user's Dropbox account.
id String(min_length=1, pattern="[-_0-9a-zA-Z]+") The ID of the file request.
url String(min_length=1) The URL of the file request.
title String(min_length=1) The title of the file request.
created Timestamp(format="%Y-%m-%dT%H:%M:%SZ") When this file request was created.
is_open Boolean Whether or not the file request is open. If the file request is closed, it will not accept any more file submissions.
file_count Int64 The 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 FileRequestDeadline? The deadline for this file request. Only set if the request has a deadline. This field is optional.
FileRequestDeadline
deadline Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The deadline for this file request.
allow_late_uploads GracePeriod? If set, allow uploads after the deadline has passed. These uploads will be marked overdue. This field is optional.
GracePeriod (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
one_day Void
two_days Void
seven_days Void
thirty_days Void
always Void
Errors
Example: disabled_for_team
{
    "error_summary": "disabled_for_team/...",
    "error": {
        ".tag": "disabled_for_team"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: not_found
{
    "error_summary": "not_found/...",
    "error": {
        ".tag": "not_found"
    }
}
Example: not_a_folder
{
    "error_summary": "not_a_folder/...",
    "error": {
        ".tag": "not_a_folder"
    }
}
Example: app_lacks_access
{
    "error_summary": "app_lacks_access/...",
    "error": {
        ".tag": "app_lacks_access"
    }
}
Example: no_permission
{
    "error_summary": "no_permission/...",
    "error": {
        ".tag": "no_permission"
    }
}
Example: email_unverified
{
    "error_summary": "email_unverified/...",
    "error": {
        ".tag": "email_unverified"
    }
}
Example: validation_error
{
    "error_summary": "validation_error/...",
    "error": {
        ".tag": "validation_error"
    }
}
GetFileRequestError (union)
There was an error retrieving the specified file request. The value will be one of the following datatypes:
disabled_for_team Void This user's Dropbox Business team doesn't allow file requests.
not_found Void This file request ID was not found.
not_a_folder Void The specified path is not a folder.
app_lacks_access Void This file request is not accessible to this app. Apps with the app folder permission can only access file requests in their app folder.
no_permission Void This user doesn't have permission to access or modify this file request.
email_unverified Void This 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_error Void There was an error validating the request. For example, the title was invalid, or there were disallowed characters in the destination path.

/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
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/list \
    --header "Authorization: Bearer "
Parameters

No parameters.

Returns
{
    "file_requests": [
        {
            "id": "oaCAVmEyrqYnkZX9955Y",
            "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y",
            "title": "Homework submission",
            "created": "2015-10-05T17:00:00Z",
            "is_open": true,
            "file_count": 3,
            "destination": "/File Requests/Homework",
            "deadline": {
                "deadline": "2020-10-12T17:00:00Z",
                "allow_late_uploads": {
                    ".tag": "seven_days"
                }
            }
        },
        {
            "id": "BAJ7IrRGicQKGToykQdB",
            "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB",
            "title": "Photo contest submission",
            "created": "2015-11-02T04:00:00Z",
            "is_open": true,
            "file_count": 105,
            "destination": "/Photo contest entries",
            "deadline": {
                "deadline": "2020-10-12T17:00:00Z"
            }
        },
        {
            "id": "rxwMPvK3ATTa0VxOJu5T",
            "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T",
            "title": "Wedding photo submission",
            "created": "2015-12-15T13:02:00Z",
            "is_open": true,
            "file_count": 37,
            "destination": "/Wedding photos"
        }
    ]
}
ListFileRequestsResult
Result for list.
file_requests List of (FileRequest) The file requests owned by this user. Apps with the app folder permission will only see file requests in their app folder.
FileRequest
A file request for receiving files into the user's Dropbox account.
id String(min_length=1, pattern="[-_0-9a-zA-Z]+") The ID of the file request.
url String(min_length=1) The URL of the file request.
title String(min_length=1) The title of the file request.
created Timestamp(format="%Y-%m-%dT%H:%M:%SZ") When this file request was created.
is_open Boolean Whether or not the file request is open. If the file request is closed, it will not accept any more file submissions.
file_count Int64 The 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 FileRequestDeadline? The deadline for this file request. Only set if the request has a deadline. This field is optional.
FileRequestDeadline
deadline Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The deadline for this file request.
allow_late_uploads GracePeriod? If set, allow uploads after the deadline has passed. These uploads will be marked overdue. This field is optional.
GracePeriod (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
one_day Void
two_days Void
seven_days Void
thirty_days Void
always Void
Errors
Example: disabled_for_team
{
    "error_summary": "disabled_for_team/...",
    "error": {
        ".tag": "disabled_for_team"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
ListFileRequestsError (union)
There was an error retrieving the file requests. The value will be one of the following datatypes:
disabled_for_team Void This user's Dropbox Business team doesn't allow file requests.

/update

Description

Update a file request.

URL Structure
https://api.dropboxapi.com/2/file_requests/update
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/file_requests/update \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"id\": \"oaCAVmEyrqYnkZX9955Y\",\"title\": \"Homework submission\",\"destination\": \"/File Requests/Homework\",\"deadline\": {\".tag\": \"update\",\"deadline\": \"2020-10-12T17:00:00Z\",\"allow_late_uploads\": \"seven_days\"},\"open\": true}"
Parameters
{
    "id": "oaCAVmEyrqYnkZX9955Y",
    "title": "Homework submission",
    "destination": "/File Requests/Homework",
    "deadline": {
        ".tag": "update",
        "deadline": "2020-10-12T17:00:00Z",
        "allow_late_uploads": "seven_days"
    },
    "open": true
}
UpdateFileRequestArgs
Arguments for update.
id String(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.
deadline UpdateFileRequestDeadline The new deadline for the file request. The default for this union is no_update.
UpdateFileRequestDeadline (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
no_update Void Do not change the file request's deadline.
update FileRequestDeadline? If None, the file request's deadline is cleared. This field is optional.
FileRequestDeadline
deadline Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The deadline for this file request.
allow_late_uploads GracePeriod? If set, allow uploads after the deadline has passed. These uploads will be marked overdue. This field is optional.
GracePeriod (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
one_day Void
two_days Void
seven_days Void
thirty_days Void
always Void
open Boolean? Whether to set this file request as open or closed. This field is optional.
Returns
{
    "id": "oaCAVmEyrqYnkZX9955Y",
    "url": "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y",
    "title": "Homework submission",
    "created": "2015-10-05T17:00:00Z",
    "is_open": true,
    "file_count": 3,
    "destination": "/File Requests/Homework",
    "deadline": {
        "deadline": "2020-10-12T17:00:00Z",
        "allow_late_uploads": {
            ".tag": "seven_days"
        }
    }
}
Example: with_deadline
{
    "id": "BAJ7IrRGicQKGToykQdB",
    "url": "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB",
    "title": "Photo contest submission",
    "created": "2015-11-02T04:00:00Z",
    "is_open": true,
    "file_count": 105,
    "destination": "/Photo contest entries",
    "deadline": {
        "deadline": "2020-10-12T17:00:00Z"
    }
}
Example: with_no_deadline
{
    "id": "rxwMPvK3ATTa0VxOJu5T",
    "url": "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T",
    "title": "Wedding photo submission",
    "created": "2015-12-15T13:02:00Z",
    "is_open": true,
    "file_count": 37,
    "destination": "/Wedding photos"
}
FileRequest
A file request for receiving files into the user's Dropbox account.
id String(min_length=1, pattern="[-_0-9a-zA-Z]+") The ID of the file request.
url String(min_length=1) The URL of the file request.
title String(min_length=1) The title of the file request.
created Timestamp(format="%Y-%m-%dT%H:%M:%SZ") When this file request was created.
is_open Boolean Whether or not the file request is open. If the file request is closed, it will not accept any more file submissions.
file_count Int64 The 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 FileRequestDeadline? The deadline for this file request. Only set if the request has a deadline. This field is optional.
FileRequestDeadline
deadline Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The deadline for this file request.
allow_late_uploads GracePeriod? If set, allow uploads after the deadline has passed. These uploads will be marked overdue. This field is optional.
GracePeriod (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
one_day Void
two_days Void
seven_days Void
thirty_days Void
always Void
Errors
Example: disabled_for_team
{
    "error_summary": "disabled_for_team/...",
    "error": {
        ".tag": "disabled_for_team"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: not_found
{
    "error_summary": "not_found/...",
    "error": {
        ".tag": "not_found"
    }
}
Example: not_a_folder
{
    "error_summary": "not_a_folder/...",
    "error": {
        ".tag": "not_a_folder"
    }
}
Example: app_lacks_access
{
    "error_summary": "app_lacks_access/...",
    "error": {
        ".tag": "app_lacks_access"
    }
}
Example: no_permission
{
    "error_summary": "no_permission/...",
    "error": {
        ".tag": "no_permission"
    }
}
Example: email_unverified
{
    "error_summary": "email_unverified/...",
    "error": {
        ".tag": "email_unverified"
    }
}
Example: validation_error
{
    "error_summary": "validation_error/...",
    "error": {
        ".tag": "validation_error"
    }
}
UpdateFileRequestError (union)
There is an error updating the file request. The value will be one of the following datatypes:
disabled_for_team Void This user's Dropbox Business team doesn't allow file requests.
not_found Void This file request ID was not found.
not_a_folder Void The specified path is not a folder.
app_lacks_access Void This file request is not accessible to this app. Apps with the app folder permission can only access file requests in their app folder.
no_permission Void This user doesn't have permission to access or modify this file request.
email_unverified Void This 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_error Void There was an error validating the request. For example, the title was invalid, or there were disallowed characters in the destination path.

files

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

/copy_batch

Description

Copy multiple files or folders to different locations at once in the user's Dropbox.
If RelocationBatchArg.allow_shared_folder is false, this route is atomic. If on entry failes, the whole transaction will abort. If RelocationBatchArg.allow_shared_folder is true, not atomicity is guaranteed, but you will be able to copy the contents of shared folders to new locations.
This route will return job ID immediately and do the async copy job in background. Please use copy_batch/check to check the job status.

URL Structure
https://api.dropboxapi.com/2/files/copy_batch
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy_batch \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"entries\": [{\"from_path\": \"/Homework/math\",\"to_path\": \"/Homework/algebra\"}],\"allow_shared_folder\": false,\"autorename\": false,\"allow_ownership_transfer\": false}"
Parameters
{
    "entries": [
        {
            "from_path": "/Homework/math",
            "to_path": "/Homework/algebra"
        }
    ],
    "allow_shared_folder": false,
    "autorename": false,
    "allow_ownership_transfer": false
}
RelocationBatchArg
entries List of (RelocationPath) List of entries to be moved or copied. Each entry is RelocationPath.
RelocationPath
from_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox to be copied or moved.
to_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox that is the destination.
allow_shared_folder Boolean If true, copy_batch will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if RelocationPath.from_path contains shared folder. This field is always true for move_batch. The default for this field is False.
autorename Boolean If 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_transfer Boolean Allow 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": [
        {
            "metadata": {
                ".tag": "file",
                "name": "Prime_Numbers.txt",
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "client_modified": "2015-05-12T15:50:38Z",
                "server_modified": "2015-05-12T15:50:38Z",
                "rev": "a1c10ce0dd78",
                "size": 7212,
                "path_lower": "/homework/math/prime_numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "sharing_info": {
                    "read_only": true,
                    "parent_shared_folder_id": "84528192421",
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
                },
                "property_groups": [
                    {
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ]
                    }
                ],
                "has_explicit_shared_members": false,
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
            }
        }
    ]
}
Example: async_job_id
{
    ".tag": "async_job_id",
    "async_job_id": "34g93hh34h04y384084"
}
Example: other
{
    ".tag": "other"
}
RelocationBatchLaunch (open union)
Result returned by copy_batch or move_batch that may either launch an asynchronous job or complete synchronously. The value will be one of the following datatypes. New values may be introduced as our API evolves.
async_job_id String(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 RelocationBatchResult
RelocationBatchResult
entries List of (RelocationBatchResultData)
RelocationBatchResultData
metadata Metadata Metadata of the relocated object.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
Errors

No errors.

/copy_batch/check

Description

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

URL Structure
https://api.dropboxapi.com/2/files/copy_batch/check
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy_batch/check \
    --header "Authorization: Bearer " \
    --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_id String(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": [
        {
            "metadata": {
                ".tag": "file",
                "name": "Prime_Numbers.txt",
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "client_modified": "2015-05-12T15:50:38Z",
                "server_modified": "2015-05-12T15:50:38Z",
                "rev": "a1c10ce0dd78",
                "size": 7212,
                "path_lower": "/homework/math/prime_numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "sharing_info": {
                    "read_only": true,
                    "parent_shared_folder_id": "84528192421",
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
                },
                "property_groups": [
                    {
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ]
                    }
                ],
                "has_explicit_shared_members": false,
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
            }
        }
    ]
}
Example: in_progress
{
    ".tag": "in_progress"
}
RelocationBatchJobStatus (union)
The value will be one of the following datatypes:
in_progress Void The asynchronous job is still in progress.
complete RelocationBatchResult The copy or move batch job has finished.
RelocationBatchResult
entries List of (RelocationBatchResultData)
RelocationBatchResultData
metadata Metadata Metadata of the relocated object.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
failed RelocationBatchError The copy or move batch job has failed with exception.
RelocationBatchError (union)
The value will be one of the following datatypes:
from_lookup LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
from_write WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
to WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
cant_copy_shared_folder Void Shared folders can't be copied.
cant_nest_shared_folder Void Your move operation would result in nested shared folders. This is not allowed.
cant_move_folder_into_itself Void You cannot move a folder into itself.
too_many_files Void The operation would involve more than 10,000 files and folders.
duplicated_or_nested_paths Void There are duplicated/nested paths among RelocationArg.from_path and RelocationArg.to_path.
cant_transfer_ownership Void Your move operation would result in an ownership transfer. You may reissue the request with the field RelocationArg.allow_ownership_transfer to true.
insufficient_quota Void The current user does not have enough space to move or copy the files.
too_many_write_operations Void There are too many write operations in user's Dropbox. Please retry this request.
Errors
Example: invalid_async_job_id
{
    "error_summary": "invalid_async_job_id/...",
    "error": {
        ".tag": "invalid_async_job_id"
    }
}
Example: internal_error
{
    "error_summary": "internal_error/...",
    "error": {
        ".tag": "internal_error"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "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. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_async_job_id Void The job ID is invalid.
internal_error Void Something 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.

/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
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy_reference/get \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/video.mp4\"}"
Parameters
{
    "path": "/video.mp4"
}
GetCopyReferenceArg
path String(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
{
    "metadata": {
        ".tag": "file",
        "name": "Prime_Numbers.txt",
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "client_modified": "2015-05-12T15:50:38Z",
        "server_modified": "2015-05-12T15:50:38Z",
        "rev": "a1c10ce0dd78",
        "size": 7212,
        "path_lower": "/homework/math/prime_numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "sharing_info": {
            "read_only": true,
            "parent_shared_folder_id": "84528192421",
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        },
        "property_groups": [
            {
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ]
            }
        ],
        "has_explicit_shared_members": false,
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    },
    "copy_reference": "z1X6ATl6aWtzOGq0c3g5Ng",
    "expires": "2045-05-12T15:50:38Z"
}
GetCopyReferenceResult
metadata Metadata Metadata of the file or folder.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
copy_reference String A copy reference to the file or folder.
expires Timestamp(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
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
GetCopyReferenceError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.

/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
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy_reference/save \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"copy_reference\": \"z1X6ATl6aWtzOGq0c3g5Ng\",\"path\": \"/video.mp4\"}"
Parameters
{
    "copy_reference": "z1X6ATl6aWtzOGq0c3g5Ng",
    "path": "/video.mp4"
}
SaveCopyReferenceArg
copy_reference String A copy reference returned by copy_reference/get.
path String(pattern="/(.|[\r\n])*") Path in the user's Dropbox that is the destination.
Returns
{
    "metadata": {
        ".tag": "file",
        "name": "Prime_Numbers.txt",
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "client_modified": "2015-05-12T15:50:38Z",
        "server_modified": "2015-05-12T15:50:38Z",
        "rev": "a1c10ce0dd78",
        "size": 7212,
        "path_lower": "/homework/math/prime_numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "sharing_info": {
            "read_only": true,
            "parent_shared_folder_id": "84528192421",
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        },
        "property_groups": [
            {
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ]
            }
        ],
        "has_explicit_shared_members": false,
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
}
SaveCopyReferenceResult
metadata Metadata The metadata of the saved file or folder in the user's Dropbox.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
Errors
Example: invalid_copy_reference
{
    "error_summary": "invalid_copy_reference/...",
    "error": {
        ".tag": "invalid_copy_reference"
    }
}
Example: no_permission
{
    "error_summary": "no_permission/...",
    "error": {
        ".tag": "no_permission"
    }
}
Example: not_found
{
    "error_summary": "not_found/...",
    "error": {
        ".tag": "not_found"
    }
}
Example: too_many_files
{
    "error_summary": "too_many_files/...",
    "error": {
        ".tag": "too_many_files"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
SaveCopyReferenceError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
invalid_copy_reference Void The copy reference is invalid.
no_permission Void You 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_found Void The file referenced by the copy reference cannot be found.
too_many_files Void The operation would involve more than 10,000 files and folders.

/copy_v2

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
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy_v2 \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"from_path\": \"/Homework/math\",\"to_path\": \"/Homework/algebra\",\"allow_shared_folder\": false,\"autorename\": false,\"allow_ownership_transfer\": false}"
Parameters
{
    "from_path": "/Homework/math",
    "to_path": "/Homework/algebra",
    "allow_shared_folder": false,
    "autorename": false,
    "allow_ownership_transfer": false
}
RelocationArg
from_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox to be copied or moved.
to_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox that is the destination.
allow_shared_folder Boolean If true, copy will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if from_path contains shared folder. This field is always true for move. The default for this field is False.
autorename Boolean If 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_transfer Boolean Allow 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",
        "name": "Prime_Numbers.txt",
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "client_modified": "2015-05-12T15:50:38Z",
        "server_modified": "2015-05-12T15:50:38Z",
        "rev": "a1c10ce0dd78",
        "size": 7212,
        "path_lower": "/homework/math/prime_numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "sharing_info": {
            "read_only": true,
            "parent_shared_folder_id": "84528192421",
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        },
        "property_groups": [
            {
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ]
            }
        ],
        "has_explicit_shared_members": false,
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
}
RelocationResult
metadata Metadata Metadata of the relocated object.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
Errors
Example: cant_copy_shared_folder
{
    "error_summary": "cant_copy_shared_folder/...",
    "error": {
        ".tag": "cant_copy_shared_folder"
    }
}
Example: cant_nest_shared_folder
{
    "error_summary": "cant_nest_shared_folder/...",
    "error": {
        ".tag": "cant_nest_shared_folder"
    }
}
Example: cant_move_folder_into_itself
{
    "error_summary": "cant_move_folder_into_itself/...",
    "error": {
        ".tag": "cant_move_folder_into_itself"
    }
}
Example: too_many_files
{
    "error_summary": "too_many_files/...",
    "error": {
        ".tag": "too_many_files"
    }
}
Example: duplicated_or_nested_paths
{
    "error_summary": "duplicated_or_nested_paths/...",
    "error": {
        ".tag": "duplicated_or_nested_paths"
    }
}
Example: cant_transfer_ownership
{
    "error_summary": "cant_transfer_ownership/...",
    "error": {
        ".tag": "cant_transfer_ownership"
    }
}
Example: insufficient_quota
{
    "error_summary": "insufficient_quota/...",
    "error": {
        ".tag": "insufficient_quota"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
RelocationError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
from_lookup LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
from_write WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
to WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
cant_copy_shared_folder Void Shared folders can't be copied.
cant_nest_shared_folder Void Your move operation would result in nested shared folders. This is not allowed.
cant_move_folder_into_itself Void You cannot move a folder into itself.
too_many_files Void The operation would involve more than 10,000 files and folders.
duplicated_or_nested_paths Void There are duplicated/nested paths among RelocationArg.from_path and RelocationArg.to_path.
cant_transfer_ownership Void Your move operation would result in an ownership transfer. You may reissue the request with the field RelocationArg.allow_ownership_transfer to true.
insufficient_quota Void The current user does not have enough space to move or copy the files.

/create_folder_v2

Description

Create a folder at a given path.

URL Structure
https://api.dropboxapi.com/2/files/create_folder_v2
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/create_folder_v2 \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/Homework/math\",\"autorename\": false}"
Parameters
{
    "path": "/Homework/math",
    "autorename": false
}
CreateFolderArg
path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)") Path in the user's Dropbox to create.
autorename Boolean If 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": {
        "name": "math",
        "id": "id:a4ayc_80_OEAAAAAAAAAXz",
        "path_lower": "/homework/math",
        "path_display": "/Homework/math",
        "sharing_info": {
            "read_only": false,
            "parent_shared_folder_id": "84528192421",
            "traverse_only": false,
            "no_access": false
        },
        "property_groups": [
            {
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ]
            }
        ]
    }
}
CreateFolderResult
metadata FolderMetadata Metadata of the created folder.
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
Errors
CreateFolderError (union)
The value will be one of the following datatypes:
path WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.

/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
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/delete_batch \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"entries\": [{\"path\": \"/Homework/math/Prime_Numbers.txt\"}]}"
Parameters
{
    "entries": [
        {
            "path": "/Homework/math/Prime_Numbers.txt"
        }
    ]
}
DeleteBatchArg
entries List of (DeleteArg)
DeleteArg
path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox to delete.
Returns
Example: complete
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "metadata": {
                ".tag": "file",
                "name": "Prime_Numbers.txt",
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "client_modified": "2015-05-12T15:50:38Z",
                "server_modified": "2015-05-12T15:50:38Z",
                "rev": "a1c10ce0dd78",
                "size": 7212,
                "path_lower": "/homework/math/prime_numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "sharing_info": {
                    "read_only": true,
                    "parent_shared_folder_id": "84528192421",
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
                },
                "property_groups": [
                    {
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ]
                    }
                ],
                "has_explicit_shared_members": false,
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
            }
        }
    ]
}
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. The value will be one of the following datatypes. New values may be introduced as our API evolves.
async_job_id String(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 DeleteBatchResult
DeleteBatchResult
entries List of (DeleteBatchResultEntry)
DeleteBatchResultEntry (union)
The value will be one of the following datatypes:
success DeleteBatchResultData
DeleteBatchResultData
metadata Metadata Metadata of the deleted object.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
failure DeleteError
DeleteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path_lookup LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
path_write WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
too_many_write_operations Void There are too many write operations in user's Dropbox. Please retry this request.
too_many_files Void There are too many files in one request. Please retry with fewer files.
Errors

No 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
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/delete_batch/check \
    --header "Authorization: Bearer " \
    --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_id String(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",
                "name": "Prime_Numbers.txt",
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "client_modified": "2015-05-12T15:50:38Z",
                "server_modified": "2015-05-12T15:50:38Z",
                "rev": "a1c10ce0dd78",
                "size": 7212,
                "path_lower": "/homework/math/prime_numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "sharing_info": {
                    "read_only": true,
                    "parent_shared_folder_id": "84528192421",
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
                },
                "property_groups": [
                    {
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ]
                    }
                ],
                "has_explicit_shared_members": false,
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
            }
        }
    ]
}
Example: in_progress
{
    ".tag": "in_progress"
}
Example: other
{
    ".tag": "other"
}
DeleteBatchJobStatus (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
in_progress Void The asynchronous job is still in progress.
complete DeleteBatchResult The batch delete has finished.
DeleteBatchResult
entries List of (DeleteBatchResultEntry)
DeleteBatchResultEntry (union)
The value will be one of the following datatypes:
success DeleteBatchResultData
DeleteBatchResultData
metadata Metadata Metadata of the deleted object.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
failure DeleteError
DeleteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path_lookup LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
path_write WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
too_many_write_operations Void There are too many write operations in user's Dropbox. Please retry this request.
too_many_files Void There are too many files in one request. Please retry with fewer files.
failed DeleteBatchError The batch delete has failed.
DeleteBatchError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
too_many_write_operationsdeprecated Void Field is deprecated. Use DeleteError.too_many_write_operations. delete_batch now provides smaller granularity about which entry has failed because of this.
Errors
Example: invalid_async_job_id
{
    "error_summary": "invalid_async_job_id/...",
    "error": {
        ".tag": "invalid_async_job_id"
    }
}
Example: internal_error
{
    "error_summary": "internal_error/...",
    "error": {
        ".tag": "internal_error"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "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. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_async_job_id Void The job ID is invalid.
internal_error Void Something 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.

/delete_v2

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
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/delete_v2 \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/Homework/math/Prime_Numbers.txt\"}"
Parameters
{
    "path": "/Homework/math/Prime_Numbers.txt"
}
DeleteArg
path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox to delete.
Returns
{
    "metadata": {
        ".tag": "file",
        "name": "Prime_Numbers.txt",
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "client_modified": "2015-05-12T15:50:38Z",
        "server_modified": "2015-05-12T15:50:38Z",
        "rev": "a1c10ce0dd78",
        "size": 7212,
        "path_lower": "/homework/math/prime_numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "sharing_info": {
            "read_only": true,
            "parent_shared_folder_id": "84528192421",
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        },
        "property_groups": [
            {
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ]
            }
        ],
        "has_explicit_shared_members": false,
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
}
DeleteResult
metadata Metadata Metadata of the deleted object.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
Errors
Example: too_many_write_operations
{
    "error_summary": "too_many_write_operations/...",
    "error": {
        ".tag": "too_many_write_operations"
    }
}
Example: too_many_files
{
    "error_summary": "too_many_files/...",
    "error": {
        ".tag": "too_many_files"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
DeleteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path_lookup LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
path_write WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
too_many_write_operations Void There are too many write operations in user's Dropbox. Please retry this request.
too_many_files Void There are too many files in one request. Please retry with fewer files.

/download

Description

Download a file from a user's Dropbox.

URL Structure
https://content.dropboxapi.com/2/files/download
Authentication
User Authentication
Endpoint format
Content-download
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/download \
    --header "Authorization: Bearer " \
    --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
path String(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
{
    "name": "Prime_Numbers.txt",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "client_modified": "2015-05-12T15:50:38Z",
    "server_modified": "2015-05-12T15:50:38Z",
    "rev": "a1c10ce0dd78",
    "size": 7212,
    "path_lower": "/homework/math/prime_numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "sharing_info": {
        "read_only": true,
        "parent_shared_folder_id": "84528192421",
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
    },
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ],
    "has_explicit_shared_members": false,
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
Errors
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
DownloadError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.

/download_zip

Description

Download a folder from the user's Dropbox, as a zip file. The folder must be less than 1 GB in size and have fewer than 10,000 total files. The input cannot be a single file.

URL Structure
https://content.dropboxapi.com/2/files/download_zip
Authentication
User Authentication
Endpoint format
Content-download
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/download_zip \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"path\": \"/Homework/math\"}"
Parameters
{
    "path": "/Homework/math"
}
Example: id
{
    "path": "id:a4ayc_80_OEAAAAAAAAAYa"
}
Example: rev
{
    "path": "rev:a1c10ce0dd78"
}
DownloadZipArg
path String(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)") The path of the folder to download.
Returns
{
    "metadata": {
        "name": "math",
        "id": "id:a4ayc_80_OEAAAAAAAAAXz",
        "path_lower": "/homework/math",
        "path_display": "/Homework/math",
        "sharing_info": {
            "read_only": false,
            "parent_shared_folder_id": "84528192421",
            "traverse_only": false,
            "no_access": false
        },
        "property_groups": [
            {
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ]
            }
        ]
    }
}
DownloadZipResult
metadata FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
Errors
Example: too_large
{
    "error_summary": "too_large/...",
    "error": {
        ".tag": "too_large"
    }
}
Example: too_many_files
{
    "error_summary": "too_many_files/...",
    "error": {
        ".tag": "too_many_files"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
DownloadZipError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
too_large Void The folder is too large to download.
too_many_files Void The folder has too many files to download.

/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
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/get_metadata \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/Homework/math\",\"include_media_info\": false,\"include_deleted\": false,\"include_has_explicit_shared_members\": false}"
Parameters
{
    "path": "/Homework/math",
    "include_media_info": false,
    "include_deleted": false,
    "include_has_explicit_shared_members": false
}
Example: id
{
    "path": "id:a4ayc_80_OEAAAAAAAAAYa",
    "include_media_info": false,
    "include_deleted": false,
    "include_has_explicit_shared_members": false
}
Example: rev
{
    "path": "rev:a1c10ce0dd78",
    "include_media_info": false,
    "include_deleted": false,
    "include_has_explicit_shared_members": false
}
GetMetadataArg
path String(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)") The path of a file or folder on Dropbox.
include_media_info Boolean If true, FileMetadata.media_info is set for photo and video. The default for this field is False.
include_deleted Boolean If 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_members Boolean If 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 TemplateFilterBase? 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.
TemplateFilterBase (open union)
This datatype comes from an imported namespace originally defined in the file_properties namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
filter_some List of (String(min_length=1, pattern="(/|ptid:).*"), min_items=1) Only templates with an ID in the supplied list will be returned (a subset of templates will be returned).
Returns
{
    ".tag": "file",
    "name": "Prime_Numbers.txt",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "client_modified": "2015-05-12T15:50:38Z",
    "server_modified": "2015-05-12T15:50:38Z",
    "rev": "a1c10ce0dd78",
    "size": 7212,
    "path_lower": "/homework/math/prime_numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "sharing_info": {
        "read_only": true,
        "parent_shared_folder_id": "84528192421",
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
    },
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ],
    "has_explicit_shared_members": false,
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
{
    ".tag": "folder",
    "name": "math",
    "id": "id:a4ayc_80_OEAAAAAAAAAXz",
    "path_lower": "/homework/math",
    "path_display": "/Homework/math",
    "sharing_info": {
        "read_only": false,
        "parent_shared_folder_id": "84528192421",
        "traverse_only": false,
        "no_access": false
    },
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ]
}
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
Errors
GetMetadataError (union)
The value will be one of the following datatypes:
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.

/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, .odp, .odt, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .rtf.
HTML previews are generated for files with the following extensions: .csv, .ods, .xls, .xlsm, .xlsx.
Other formats will return an unsupported extension error.

URL Structure
https://content.dropboxapi.com/2/files/get_preview
Authentication
User Authentication
Endpoint format
Content-download
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/get_preview \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"path\": \"/word.docx\"}"
Parameters
{
    "path": "/word.docx"
}
Example: id
{
    "path": "id:a4ayc_80_OEAAAAAAAAAYa"
}
Example: rev
{
    "path": "rev:a1c10ce0dd78"
}
PreviewArg
path String(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
{
    "name": "Prime_Numbers.txt",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "client_modified": "2015-05-12T15:50:38Z",
    "server_modified": "2015-05-12T15:50:38Z",
    "rev": "a1c10ce0dd78",
    "size": 7212,
    "path_lower": "/homework/math/prime_numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "sharing_info": {
        "read_only": true,
        "parent_shared_folder_id": "84528192421",
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
    },
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ],
    "has_explicit_shared_members": false,
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
Errors
Example: in_progress
{
    "error_summary": "in_progress/...",
    "error": {
        ".tag": "in_progress"
    }
}
Example: unsupported_extension
{
    "error_summary": "unsupported_extension/...",
    "error": {
        ".tag": "unsupported_extension"
    }
}
Example: unsupported_content
{
    "error_summary": "unsupported_content/...",
    "error": {
        ".tag": "unsupported_content"
    }
}
PreviewError (union)
The value will be one of the following datatypes:
path LookupError An error occurs when downloading metadata for the file.
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
in_progress Void This preview generation is still in progress and the file is not ready for preview yet.
unsupported_extension Void The file extension is not supported preview generation.
unsupported_content Void The file content is not supported for preview generation.

/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 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
Authentication
User Authentication
Endpoint format
Content-download
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/get_thumbnail \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"path\": \"/image.jpg\",\"format\": \"jpeg\",\"size\": \"w64h64\"}"
Parameters
{
    "path": "/image.jpg",
    "format": "jpeg",
    "size": "w64h64"
}
Example: id
{
    "path": "id:a4ayc_80_OEAAAAAAAAAYa",
    "format": "jpeg",
    "size": "w64h64"
}
Example: rev
{
    "path": "rev:a1c10ce0dd78",
    "format": "jpeg",
    "size": "w64h64"
}
ThumbnailArg
path String(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)") The path to the image file you want to thumbnail.
format ThumbnailFormat The format for the thumbnail image, jpeg (default) or png. For images that are photos, jpeg should be preferred, while png is better for screenshots and digital arts. The default for this union is jpeg.
ThumbnailFormat (union)
The value will be one of the following datatypes:
jpeg Void
png Void
size ThumbnailSize The size for the thumbnail image. The default for this union is w64h64.
ThumbnailSize (union)
The value will be one of the following datatypes:
w32h32 Void 32 by 32 px.
w64h64 Void 64 by 64 px.
w128h128 Void 128 by 128 px.
w640h480 Void 640 by 480 px.
w1024h768 Void 1024 by 768.
Returns
{
    "name": "Prime_Numbers.txt",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "client_modified": "2015-05-12T15:50:38Z",
    "server_modified": "2015-05-12T15:50:38Z",
    "rev": "a1c10ce0dd78",
    "size": 7212,
    "path_lower": "/homework/math/prime_numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "sharing_info": {
        "read_only": true,
        "parent_shared_folder_id": "84528192421",
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
    },
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ],
    "has_explicit_shared_members": false,
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
Errors
Example: unsupported_extension
{
    "error_summary": "unsupported_extension/...",
    "error": {
        ".tag": "unsupported_extension"
    }
}
Example: unsupported_image
{
    "error_summary": "unsupported_image/...",
    "error": {
        ".tag": "unsupported_image"
    }
}
Example: conversion_error
{
    "error_summary": "conversion_error/...",
    "error": {
        ".tag": "conversion_error"
    }
}
ThumbnailError (union)
The value will be one of the following datatypes:
path LookupError An error occurs when downloading metadata for the image.
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
unsupported_extension Void The file extension doesn't allow conversion to a thumbnail.
unsupported_image Void The image cannot be converted to a thumbnail.
conversion_error Void An error occurs during thumbnail conversion.

/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 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
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/get_thumbnail_batch \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"entries\": [{\"path\": \"/image.jpg\",\"format\": \"jpeg\",\"size\": \"w64h64\"}]}"
Parameters
{
    "entries": [
        {
            "path": "/image.jpg",
            "format": "jpeg",
            "size": "w64h64"
        }
    ]
}
GetThumbnailBatchArg
Arguments for get_thumbnail_batch.
entries List of (ThumbnailArg) List of files to get thumbnails.
ThumbnailArg
path String(pattern="(/(.|[\r\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)") The path to the image file you want to thumbnail.
format ThumbnailFormat The format for the thumbnail image, jpeg (default) or png. For images that are photos, jpeg should be preferred, while png is better for screenshots and digital arts. The default for this union is jpeg.
ThumbnailFormat (union)
The value will be one of the following datatypes:
jpeg Void
png Void
size ThumbnailSize The size for the thumbnail image. The default for this union is w64h64.
ThumbnailSize (union)
The value will be one of the following datatypes:
w32h32 Void 32 by 32 px.
w64h64 Void 64 by 64 px.
w128h128 Void 128 by 128 px.
w640h480 Void 640 by 480 px.
w1024h768 Void 1024 by 768.
Returns
{
    "entries": [
        {
            ".tag": "success",
            "metadata": {
                "name": "Prime_Numbers.txt",
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "client_modified": "2015-05-12T15:50:38Z",
                "server_modified": "2015-05-12T15:50:38Z",
                "rev": "a1c10ce0dd78",
                "size": 7212,
                "path_lower": "/homework/math/prime_numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "sharing_info": {
                    "read_only": true,
                    "parent_shared_folder_id": "84528192421",
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
                },
                "property_groups": [
                    {
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ]
                    }
                ],
                "has_explicit_shared_members": false,
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
            },
            "thumbnail": "iVBORw0KGgoAAAANSUhEUgAAAdcAAABrCAMAAAI="
        }
    ]
}
GetThumbnailBatchResult
entries List of (GetThumbnailBatchResultEntry) List of files and their thumbnails.
GetThumbnailBatchResultEntry (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
success GetThumbnailBatchResultData
GetThumbnailBatchResultData
metadata FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
thumbnail String
failure ThumbnailError The result for this file if it was an error.
ThumbnailError (union)
The value will be one of the following datatypes:
path LookupError An error occurs when downloading metadata for the image.
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
unsupported_extension Void The file extension doesn't allow conversion to a thumbnail.
unsupported_image Void The image cannot be converted to a thumbnail.
conversion_error Void An error occurs during thumbnail conversion.
Errors
Example: too_many_files
{
    "error_summary": "too_many_files/...",
    "error": {
        ".tag": "too_many_files"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
GetThumbnailBatchError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
too_many_files Void The operation involves more than 25 files.

/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, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/list_folder \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/Homework/math\",\"recursive\": false,\"include_media_info\": false,\"include_deleted\": false,\"include_has_explicit_shared_members\": false,\"include_mounted_folders\": true}"
Parameters
{
    "path": "/Homework/math",
    "recursive": false,
    "include_media_info": false,
    "include_deleted": false,
    "include_has_explicit_shared_members": false,
    "include_mounted_folders": true
}
ListFolderArg
path String(pattern="(/(.|[\r\n])*)?|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file.
recursive Boolean If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders. The default for this field is False.
include_media_info Boolean If true, FileMetadata.media_info is set for photo and video. The default for this field is False.
include_deleted Boolean If 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_members Boolean If 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_folders Boolean If 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? 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 SharedLink? 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 TemplateFilterBase? 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.
TemplateFilterBase (open union)
This datatype comes from an imported namespace originally defined in the file_properties namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
filter_some List of (String(min_length=1, pattern="(/|ptid:).*"), min_items=1) Only templates with an ID in the supplied list will be returned (a subset of templates will be returned).
Returns
{
    "entries": [
        {
            ".tag": "file",
            "name": "Prime_Numbers.txt",
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "client_modified": "2015-05-12T15:50:38Z",
            "server_modified": "2015-05-12T15:50:38Z",
            "rev": "a1c10ce0dd78",
            "size": 7212,
            "path_lower": "/homework/math/prime_numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "sharing_info": {
                "read_only": true,
                "parent_shared_folder_id": "84528192421",
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
            },
            "property_groups": [
                {
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ]
                }
            ],
            "has_explicit_shared_members": false,
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        },
        {
            ".tag": "folder",
            "name": "math",
            "id": "id:a4ayc_80_OEAAAAAAAAAXz",
            "path_lower": "/homework/math",
            "path_display": "/Homework/math",
            "sharing_info": {
                "read_only": false,
                "parent_shared_folder_id": "84528192421",
                "traverse_only": false,
                "no_access": false
            },
            "property_groups": [
                {
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ]
                }
            ]
        }
    ],
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "has_more": false
}
ListFolderResult
entries List of (Metadata) The files and (direct) subfolders in the folder.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
cursor String(min_length=1) Pass the cursor into list_folder/continue to see what's changed in the folder since your previous query.
has_more Boolean If true, then there are more entries available. Pass the cursor to list_folder/continue to retrieve the rest.
Errors
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
ListFolderError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.

/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, Dropbox-API-Select-Admin (Whole Team)
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/list_folder/continue \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"cursor\": \"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"
Parameters
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
ListFolderContinueArg
cursor String(min_length=1) The cursor returned by your last call to list_folder or list_folder/continue.
Returns
{
    "entries": [
        {
            ".tag": "file",
            "name": "Prime_Numbers.txt",
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "client_modified": "2015-05-12T15:50:38Z",
            "server_modified": "2015-05-12T15:50:38Z",
            "rev": "a1c10ce0dd78",
            "size": 7212,
            "path_lower": "/homework/math/prime_numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "sharing_info": {
                "read_only": true,
                "parent_shared_folder_id": "84528192421",
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
            },
            "property_groups": [
                {
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ]
                }
            ],
            "has_explicit_shared_members": false,
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        },
        {
            ".tag": "folder",
            "name": "math",
            "id": "id:a4ayc_80_OEAAAAAAAAAXz",
            "path_lower": "/homework/math",
            "path_display": "/Homework/math",
            "sharing_info": {
                "read_only": false,
                "parent_shared_folder_id": "84528192421",
                "traverse_only": false,
                "no_access": false
            },
            "property_groups": [
                {
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ]
                }
            ]
        }
    ],
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
    "has_more": false
}
ListFolderResult
entries List of (Metadata) The files and (direct) subfolders in the folder.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
cursor String(min_length=1) Pass the cursor into list_folder/continue to see what's changed in the folder since your previous query.
has_more Boolean If true, then there are more entries available. Pass the cursor to list_folder/continue to retrieve the rest.
Errors
Example: reset
{
    "error_summary": "reset/...",
    "error": {
        ".tag": "reset"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
ListFolderContinueError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
reset Void Indicates that the cursor has been invalidated. Call list_folder to obtain a new cursor.

/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
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/list_folder/get_latest_cursor \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/Homework/math\",\"recursive\": false,\"include_media_info\": false,\"include_deleted\": false,\"include_has_explicit_shared_members\": false,\"include_mounted_folders\": true}"
Parameters
{
    "path": "/Homework/math",
    "recursive": false,
    "include_media_info": false,
    "include_deleted": false,
    "include_has_explicit_shared_members": false,
    "include_mounted_folders": true
}
ListFolderArg
path String(pattern="(/(.|[\r\n])*)?|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file.
recursive Boolean If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders. The default for this field is False.
include_media_info Boolean If true, FileMetadata.media_info is set for photo and video. The default for this field is False.
include_deleted Boolean If 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_members Boolean If 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_folders Boolean If 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? 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 SharedLink? 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 TemplateFilterBase? 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.
TemplateFilterBase (open union)
This datatype comes from an imported namespace originally defined in the file_properties namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
filter_some List of (String(min_length=1, pattern="(/|ptid:).*"), min_items=1) Only templates with an ID in the supplied list will be returned (a subset of templates will be returned).
Returns
{
    "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
}
ListFolderGetLatestCursorResult
cursor String(min_length=1) Pass the cursor into list_folder/continue to see what's changed in the folder since your previous query.
Errors
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
ListFolderError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.

/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
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
cursor String(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.
timeout UInt64 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
changes Boolean Indicates 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_summary": "reset/...",
    "error": {
        ".tag": "reset"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
ListFolderLongpollError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
reset Void Indicates that the cursor has been invalidated. Call list_folder to obtain a new cursor.

/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
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/list_revisions \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/root/word.docx\",\"mode\": \"path\",\"limit\": 10}"
Parameters
{
    "path": "/root/word.docx",
    "mode": "path",
    "limit": 10
}
ListRevisionsArg
path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") The path to the file you want to see the revisions of.
mode ListRevisionsMode Determines the behavior of the API in listing the revisions for a given file path or id. The default for this union is path.
ListRevisionsMode (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path Void Returns revisions with the same file path as identified by the latest file entry at the given file path or id.
id Void Returns revisions with the same file id as identified by the latest file entry at the given file path or id.
limit UInt64 The maximum number of revision entries returned. The default for this field is 10.
Returns
{
    "is_deleted": false,
    "entries": [
        {
            "name": "Prime_Numbers.txt",
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "client_modified": "2015-05-12T15:50:38Z",
            "server_modified": "2015-05-12T15:50:38Z",
            "rev": "a1c10ce0dd78",
            "size": 7212,
            "path_lower": "/homework/math/prime_numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "sharing_info": {
                "read_only": true,
                "parent_shared_folder_id": "84528192421",
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
            },
            "property_groups": [
                {
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ]
                }
            ],
            "has_explicit_shared_members": false,
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        }
    ]
}
ListRevisionsResult
is_deleted Boolean If the file identified by the latest revision in the response is either deleted or moved.
entries List of (FileMetadata) The revisions for the file. Only revisions that are not deleted will show up here.
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
server_deleted Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The time of deletion if the file was deleted. This field is optional.
Errors
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
ListRevisionsError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.

/move_batch

Description

Move multiple files or folders to different locations at once in the user's Dropbox.
This route is 'all or nothing', which means if one entry fails, the whole transaction will abort.
This route will return job ID immediately and do the async moving job in background. Please use move_batch/check to check the job status.

URL Structure
https://api.dropboxapi.com/2/files/move_batch
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/move_batch \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"entries\": [{\"from_path\": \"/Homework/math\",\"to_path\": \"/Homework/algebra\"}],\"allow_shared_folder\": false,\"autorename\": false,\"allow_ownership_transfer\": false}"
Parameters
{
    "entries": [
        {
            "from_path": "/Homework/math",
            "to_path": "/Homework/algebra"
        }
    ],
    "allow_shared_folder": false,
    "autorename": false,
    "allow_ownership_transfer": false
}
RelocationBatchArg
entries List of (RelocationPath) List of entries to be moved or copied. Each entry is RelocationPath.
RelocationPath
from_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox to be copied or moved.
to_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox that is the destination.
allow_shared_folder Boolean If true, copy_batch will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if RelocationPath.from_path contains shared folder. This field is always true for move_batch. The default for this field is False.
autorename Boolean If 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_transfer Boolean Allow 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": [
        {
            "metadata": {
                ".tag": "file",
                "name": "Prime_Numbers.txt",
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "client_modified": "2015-05-12T15:50:38Z",
                "server_modified": "2015-05-12T15:50:38Z",
                "rev": "a1c10ce0dd78",
                "size": 7212,
                "path_lower": "/homework/math/prime_numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "sharing_info": {
                    "read_only": true,
                    "parent_shared_folder_id": "84528192421",
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
                },
                "property_groups": [
                    {
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ]
                    }
                ],
                "has_explicit_shared_members": false,
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
            }
        }
    ]
}
Example: async_job_id
{
    ".tag": "async_job_id",
    "async_job_id": "34g93hh34h04y384084"
}
Example: other
{
    ".tag": "other"
}
RelocationBatchLaunch (open union)
Result returned by copy_batch or move_batch that may either launch an asynchronous job or complete synchronously. The value will be one of the following datatypes. New values may be introduced as our API evolves.
async_job_id String(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 RelocationBatchResult
RelocationBatchResult
entries List of (RelocationBatchResultData)
RelocationBatchResultData
metadata Metadata Metadata of the relocated object.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
Errors

No errors.

/move_batch/check

Description

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

URL Structure
https://api.dropboxapi.com/2/files/move_batch/check
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/move_batch/check \
    --header "Authorization: Bearer " \
    --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_id String(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": [
        {
            "metadata": {
                ".tag": "file",
                "name": "Prime_Numbers.txt",
                "id": "id:a4ayc_80_OEAAAAAAAAAXw",
                "client_modified": "2015-05-12T15:50:38Z",
                "server_modified": "2015-05-12T15:50:38Z",
                "rev": "a1c10ce0dd78",
                "size": 7212,
                "path_lower": "/homework/math/prime_numbers.txt",
                "path_display": "/Homework/math/Prime_Numbers.txt",
                "sharing_info": {
                    "read_only": true,
                    "parent_shared_folder_id": "84528192421",
                    "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
                },
                "property_groups": [
                    {
                        "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                        "fields": [
                            {
                                "name": "Security Policy",
                                "value": "Confidential"
                            }
                        ]
                    }
                ],
                "has_explicit_shared_members": false,
                "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
            }
        }
    ]
}
Example: in_progress
{
    ".tag": "in_progress"
}
RelocationBatchJobStatus (union)
The value will be one of the following datatypes:
in_progress Void The asynchronous job is still in progress.
complete RelocationBatchResult The copy or move batch job has finished.
RelocationBatchResult
entries List of (RelocationBatchResultData)
RelocationBatchResultData
metadata Metadata Metadata of the relocated object.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
failed RelocationBatchError The copy or move batch job has failed with exception.
RelocationBatchError (union)
The value will be one of the following datatypes:
from_lookup LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
from_write WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
to WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
cant_copy_shared_folder Void Shared folders can't be copied.
cant_nest_shared_folder Void Your move operation would result in nested shared folders. This is not allowed.
cant_move_folder_into_itself Void You cannot move a folder into itself.
too_many_files Void The operation would involve more than 10,000 files and folders.
duplicated_or_nested_paths Void There are duplicated/nested paths among RelocationArg.from_path and RelocationArg.to_path.
cant_transfer_ownership Void Your move operation would result in an ownership transfer. You may reissue the request with the field RelocationArg.allow_ownership_transfer to true.
insufficient_quota Void The current user does not have enough space to move or copy the files.
too_many_write_operations Void There are too many write operations in user's Dropbox. Please retry this request.
Errors
Example: invalid_async_job_id
{
    "error_summary": "invalid_async_job_id/...",
    "error": {
        ".tag": "invalid_async_job_id"
    }
}
Example: internal_error
{
    "error_summary": "internal_error/...",
    "error": {
        ".tag": "internal_error"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "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. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_async_job_id Void The job ID is invalid.
internal_error Void Something 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.

/move_v2

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.

URL Structure
https://api.dropboxapi.com/2/files/move_v2
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/move_v2 \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"from_path\": \"/Homework/math\",\"to_path\": \"/Homework/algebra\",\"allow_shared_folder\": false,\"autorename\": false,\"allow_ownership_transfer\": false}"
Parameters
{
    "from_path": "/Homework/math",
    "to_path": "/Homework/algebra",
    "allow_shared_folder": false,
    "autorename": false,
    "allow_ownership_transfer": false
}
RelocationArg
from_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox to be copied or moved.
to_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox that is the destination.
allow_shared_folder Boolean If true, copy will copy contents in shared folder, otherwise RelocationError.cant_copy_shared_folder will be returned if from_path contains shared folder. This field is always true for move. The default for this field is False.
autorename Boolean If 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_transfer Boolean Allow 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",
        "name": "Prime_Numbers.txt",
        "id": "id:a4ayc_80_OEAAAAAAAAAXw",
        "client_modified": "2015-05-12T15:50:38Z",
        "server_modified": "2015-05-12T15:50:38Z",
        "rev": "a1c10ce0dd78",
        "size": 7212,
        "path_lower": "/homework/math/prime_numbers.txt",
        "path_display": "/Homework/math/Prime_Numbers.txt",
        "sharing_info": {
            "read_only": true,
            "parent_shared_folder_id": "84528192421",
            "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        },
        "property_groups": [
            {
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ]
            }
        ],
        "has_explicit_shared_members": false,
        "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
}
RelocationResult
metadata Metadata Metadata of the relocated object.
Metadata (datatype with subtypes)
Metadata for a file or folder. This datatype will be one of the following subtypes:
file FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
folder FolderMetadata
FolderMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the folder.
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.
shared_folder_iddeprecated String(pattern="[-_0-9a-zA-Z:]+")? Field is deprecated. Please use sharing_info instead. This field is optional.
sharing_info FolderSharingInfo? Set if the folder is contained in a shared folder or is a shared folder mount point. This field is optional.
FolderSharingInfo
Sharing info for a folder which is contained in a shared folder or is a shared folder mount point.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? Set if the folder is contained by a shared folder. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? If this folder is a shared folder mount point, the ID of the shared folder mounted at this location. This field is optional.
traverse_only Boolean Specifies that the folder can only be traversed and the user can only see a limited subset of the contents of this folder because they don't have read access to this folder. They do, however, have access to some sub folder. The default for this field is False.
no_access Boolean Specifies that the folder cannot be accessed by the user. The default for this field is False.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. Note that only properties associated with user-owned templates, not team-owned templates, can be attached to folders. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
deleted DeletedMetadata
DeletedMetadata
Indicates that there used to be a file or folder at this path, but it no longer exists.
name String The last component of the path (including extension). This never contains a slash.
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.
Errors
Example: cant_copy_shared_folder
{
    "error_summary": "cant_copy_shared_folder/...",
    "error": {
        ".tag": "cant_copy_shared_folder"
    }
}
Example: cant_nest_shared_folder
{
    "error_summary": "cant_nest_shared_folder/...",
    "error": {
        ".tag": "cant_nest_shared_folder"
    }
}
Example: cant_move_folder_into_itself
{
    "error_summary": "cant_move_folder_into_itself/...",
    "error": {
        ".tag": "cant_move_folder_into_itself"
    }
}
Example: too_many_files
{
    "error_summary": "too_many_files/...",
    "error": {
        ".tag": "too_many_files"
    }
}
Example: duplicated_or_nested_paths
{
    "error_summary": "duplicated_or_nested_paths/...",
    "error": {
        ".tag": "duplicated_or_nested_paths"
    }
}
Example: cant_transfer_ownership
{
    "error_summary": "cant_transfer_ownership/...",
    "error": {
        ".tag": "cant_transfer_ownership"
    }
}
Example: insufficient_quota
{
    "error_summary": "insufficient_quota/...",
    "error": {
        ".tag": "insufficient_quota"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
RelocationError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
from_lookup LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
from_write WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
to WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
cant_copy_shared_folder Void Shared folders can't be copied.
cant_nest_shared_folder Void Your move operation would result in nested shared folders. This is not allowed.
cant_move_folder_into_itself Void You cannot move a folder into itself.
too_many_files Void The operation would involve more than 10,000 files and folders.
duplicated_or_nested_paths Void There are duplicated/nested paths among RelocationArg.from_path and RelocationArg.to_path.
cant_transfer_ownership Void Your move operation would result in an ownership transfer. You may reissue the request with the field RelocationArg.allow_ownership_transfer to true.
insufficient_quota Void The current user does not have enough space to move or copy the files.

/permanently_delete

Description

Permanently delete the file or folder at a given path (see https://www.dropbox.com/en/help/40).
Note: This endpoint is only available for Dropbox Business apps.

URL Structure
https://api.dropboxapi.com/2/files/permanently_delete
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/permanently_delete \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/Homework/math/Prime_Numbers.txt\"}"
Parameters
{
    "path": "/Homework/math/Prime_Numbers.txt"
}
DeleteArg
path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox to delete.
Returns

No return values.

Errors
Example: too_many_write_operations
{
    "error_summary": "too_many_write_operations/...",
    "error": {
        ".tag": "too_many_write_operations"
    }
}
Example: too_many_files
{
    "error_summary": "too_many_files/...",
    "error": {
        ".tag": "too_many_files"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
DeleteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path_lookup LookupError
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
path_write WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
too_many_write_operations Void There are too many write operations in user's Dropbox. Please retry this request.
too_many_files Void There are too many files in one request. Please retry with fewer files.

/restore

Description

Restore a file to a specific revision.

URL Structure
https://api.dropboxapi.com/2/files/restore
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/restore \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/root/word.docx\",\"rev\": \"a1c10ce0dd78\"}"
Parameters
{
    "path": "/root/word.docx",
    "rev": "a1c10ce0dd78"
}
RestoreArg
path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)") The path to the file you want to restore.
rev String(min_length=9, pattern="[0-9a-f]+") The revision to restore for the file.
Returns
{
    "name": "Prime_Numbers.txt",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "client_modified": "2015-05-12T15:50:38Z",
    "server_modified": "2015-05-12T15:50:38Z",
    "rev": "a1c10ce0dd78",
    "size": 7212,
    "path_lower": "/homework/math/prime_numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "sharing_info": {
        "read_only": true,
        "parent_shared_folder_id": "84528192421",
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
    },
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ],
    "has_explicit_shared_members": false,
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
Errors
Example: invalid_revision
{
    "error_summary": "invalid_revision/...",
    "error": {
        ".tag": "invalid_revision"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
RestoreError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path_lookup LookupError An error occurs when downloading metadata for the file.
LookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
path_write WriteError An error occurs when trying to restore the file to that path.
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
invalid_revision Void The revision is invalid. It may point to a different file.

/save_url

Description

Save a specified URL into a file in user's Dropbox. 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
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/save_url \
    --header "Authorization: Bearer " \
    --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
path String(pattern="/(.|[\r\n])*") The path in Dropbox where the URL will be saved to.
url String The URL to be saved.
Returns
{
    ".tag": "complete",
    "name": "Prime_Numbers.txt",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "client_modified": "2015-05-12T15:50:38Z",
    "server_modified": "2015-05-12T15:50:38Z",
    "rev": "a1c10ce0dd78",
    "size": 7212,
    "path_lower": "/homework/math/prime_numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "sharing_info": {
        "read_only": true,
        "parent_shared_folder_id": "84528192421",
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
    },
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ],
    "has_explicit_shared_members": false,
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
SaveUrlResult (union)
The value will be one of the following datatypes:
async_job_id String(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 FileMetadata Metadata of the file where the URL is saved to.
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
Errors
Example: download_failed
{
    "error_summary": "download_failed/...",
    "error": {
        ".tag": "download_failed"
    }
}
Example: invalid_url
{
    "error_summary": "invalid_url/...",
    "error": {
        ".tag": "invalid_url"
    }
}
Example: not_found
{
    "error_summary": "not_found/...",
    "error": {
        ".tag": "not_found"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
SaveUrlError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
download_failed Void Failed downloading the given URL.
invalid_url Void The given URL is invalid.
not_found Void The file where the URL is saved to no longer exists.

/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
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/save_url/check_job_status \
    --header "Authorization: Bearer " \
    --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_id String(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)
The value will be one of the following datatypes:
in_progress Void The asynchronous job is still in progress.
complete FileMetadata Metadata of the file where the URL is saved to.
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
failed SaveUrlError
SaveUrlError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path WriteError
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
download_failed Void Failed downloading the given URL.
invalid_url Void The given URL is invalid.
not_found Void The file where the URL is saved to no longer exists.
Errors
Example: invalid_async_job_id
{
    "error_summary": "invalid_async_job_id/...",
    "error": {
        ".tag": "invalid_async_job_id"
    }
}
Example: internal_error
{
    "error_summary": "internal_error/...",
    "error": {
        ".tag": "internal_error"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "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. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_async_job_id Void The job ID is invalid.
internal_error Void Something 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.

/upload

Description

Create a new file with the contents provided in the request.
Do not use this to upload a file larger than 150 MB. Instead, create an upload session with upload_session/start.

URL Structure
https://content.dropboxapi.com/2/files/upload
Authentication
User Authentication
Endpoint format
Content-upload
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/upload \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"path\": \"/Homework/math/Matrices.txt\",\"mode\": \"add\",\"autorename\": true,\"mute\": false}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "path": "/Homework/math/Matrices.txt",
    "mode": "add",
    "autorename": true,
    "mute": false
}
Example: update
{
    "path": "/Homework/math/Matrices.txt",
    "mode": {
        ".tag": "update",
        "update": "a1c10ce0dd78"
    },
    "autorename": false,
    "mute": false,
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ]
}
CommitInfo
path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox to save the file.
mode WriteMode Selects what to do if the file already exists. The default for this union is add.
WriteMode (union)
Your intent when writing a file to some path. This is used to determine what constitutes a conflict and what the autorename strategy is.
In some situations, the conflict behavior is identical: (a) If the target path doesn't refer to anything, the file is always written; no conflict. (b) If the target path refers to a folder, it's always a conflict. (c) If the target path refers to a file with identical contents, nothing gets written; no conflict.
The conflict checking differs in the case where there's a file at the target path with contents different from the contents you're trying to write. The value will be one of the following datatypes:
add Void Do not overwrite an existing file if there is a conflict. The autorename strategy is to append a number to the file name. For example, "document.txt" might become "document (2).txt".
overwrite Void Always overwrite the existing file. The autorename strategy is the same as it is for add.
update String(min_length=9, pattern="[0-9a-f]+") Overwrite if the given "rev" matches the existing file's "rev". The autorename strategy is to append the string "conflicted copy" to the file name. For example, "document.txt" might become "document (conflicted copy).txt" or "document (Panda's conflicted copy).txt".
autorename Boolean If 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.
mute Boolean Normally, 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_groups List of (PropertyGroup)? List of custom properties to add to file. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
Returns
{
    "name": "Prime_Numbers.txt",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "client_modified": "2015-05-12T15:50:38Z",
    "server_modified": "2015-05-12T15:50:38Z",
    "rev": "a1c10ce0dd78",
    "size": 7212,
    "path_lower": "/homework/math/prime_numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "sharing_info": {
        "read_only": true,
        "parent_shared_folder_id": "84528192421",
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
    },
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ],
    "has_explicit_shared_members": false,
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
Errors
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
UploadError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
path UploadWriteFailed Unable to save the uploaded contents to a file.
UploadWriteFailed
reason WriteError The reason why the file couldn't be saved.
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
upload_session_id String The upload session ID; this may be used to retry the commit.
properties_error InvalidPropertyGroupError The supplied property group is invalid.
InvalidPropertyGroupError (union)
This datatype comes from an imported namespace originally defined in the file_properties namespace. The value will be one of the following datatypes:
template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.
restricted_content Void You do not have permission to modify this template.
path LookupError
LookupError (open union)
This datatype comes from an imported namespace originally defined in the file_properties namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String
not_found Void There is nothing at the given path.
not_file Void We were expecting a file, but the given path refers to something that isn't a file.
not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.
restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.
unsupported_folder Void This folder cannot be tagged. Tagging folders is not supported for team-owned templates.
property_field_too_large Void One or more of the supplied property field values is too large.
does_not_fit_template Void One or more of the supplied property fields does not conform to the template specifications.

/upload_session/append_v2

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

URL Structure
https://content.dropboxapi.com/2/files/upload_session/append_v2
Authentication
User Authentication
Endpoint format
Content-upload
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/upload_session/append_v2 \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"cursor\": {\"session_id\": \"1234faaf0678bcde\",\"offset\": 0},\"close\": false}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "cursor": {
        "session_id": "1234faaf0678bcde",
        "offset": 0
    },
    "close": false
}
UploadSessionAppendArg
cursor UploadSessionCursor Contains the upload session ID and the offset.
UploadSessionCursor
session_id String The upload session ID (returned by upload_session/start).
offset UInt64 The amount of data that has been uploaded so far. We use this to make sure upload data isn't lost or duplicated in the event of a network error.
close Boolean If true, the current session will be closed, at which point you won't be able to call upload_session/append_v2 anymore with the current session. The default for this field is False.
Returns

No return values.

Errors
Example: not_found
{
    "error_summary": "not_found/...",
    "error": {
        ".tag": "not_found"
    }
}
Example: closed
{
    "error_summary": "closed/...",
    "error": {
        ".tag": "closed"
    }
}
Example: not_closed
{
    "error_summary": "not_closed/...",
    "error": {
        ".tag": "not_closed"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
UploadSessionLookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
not_found Void The upload session ID was not found or has expired. Upload sessions are valid for 48 hours.
incorrect_offset UploadSessionOffsetError The 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.
UploadSessionOffsetError
correct_offset UInt64 The offset up to which data has been collected.
closed Void You are attempting to append data to an upload session that has alread been closed (i.e. committed).
not_closed Void The session must be closed before calling upload_session/finish_batch.

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

URL Structure
https://content.dropboxapi.com/2/files/upload_session/finish
Authentication
User Authentication
Endpoint format
Content-upload
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/upload_session/finish \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"cursor\": {\"session_id\": \"1234faaf0678bcde\",\"offset\": 0},\"commit\": {\"path\": \"/Homework/math/Matrices.txt\",\"mode\": \"add\",\"autorename\": true,\"mute\": false}}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "cursor": {
        "session_id": "1234faaf0678bcde",
        "offset": 0
    },
    "commit": {
        "path": "/Homework/math/Matrices.txt",
        "mode": "add",
        "autorename": true,
        "mute": false
    }
}
Example: update
{
    "cursor": {
        "session_id": "1234faaf0678bcde",
        "offset": 0
    },
    "commit": {
        "path": "/Homework/math/Matrices.txt",
        "mode": {
            ".tag": "update",
            "update": "a1c10ce0dd78"
        },
        "autorename": false,
        "mute": false,
        "property_groups": [
            {
                "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                "fields": [
                    {
                        "name": "Security Policy",
                        "value": "Confidential"
                    }
                ]
            }
        ]
    }
}
UploadSessionFinishArg
cursor UploadSessionCursor Contains the upload session ID and the offset.
UploadSessionCursor
session_id String The upload session ID (returned by upload_session/start).
offset UInt64 The amount of data that has been uploaded so far. We use this to make sure upload data isn't lost or duplicated in the event of a network error.
commit CommitInfo Contains the path and other optional modifiers for the commit.
CommitInfo
path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox to save the file.
mode WriteMode Selects what to do if the file already exists. The default for this union is add.
WriteMode (union)
Your intent when writing a file to some path. This is used to determine what constitutes a conflict and what the autorename strategy is.
In some situations, the conflict behavior is identical: (a) If the target path doesn't refer to anything, the file is always written; no conflict. (b) If the target path refers to a folder, it's always a conflict. (c) If the target path refers to a file with identical contents, nothing gets written; no conflict.
The conflict checking differs in the case where there's a file at the target path with contents different from the contents you're trying to write. The value will be one of the following datatypes:
add Void Do not overwrite an existing file if there is a conflict. The autorename strategy is to append a number to the file name. For example, "document.txt" might become "document (2).txt".
overwrite Void Always overwrite the existing file. The autorename strategy is the same as it is for add.
update String(min_length=9, pattern="[0-9a-f]+") Overwrite if the given "rev" matches the existing file's "rev". The autorename strategy is to append the string "conflicted copy" to the file name. For example, "document.txt" might become "document (conflicted copy).txt" or "document (Panda's conflicted copy).txt".
autorename Boolean If 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.
mute Boolean Normally, 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_groups List of (PropertyGroup)? List of custom properties to add to file. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
Returns
{
    "name": "Prime_Numbers.txt",
    "id": "id:a4ayc_80_OEAAAAAAAAAXw",
    "client_modified": "2015-05-12T15:50:38Z",
    "server_modified": "2015-05-12T15:50:38Z",
    "rev": "a1c10ce0dd78",
    "size": 7212,
    "path_lower": "/homework/math/prime_numbers.txt",
    "path_display": "/Homework/math/Prime_Numbers.txt",
    "sharing_info": {
        "read_only": true,
        "parent_shared_folder_id": "84528192421",
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
    },
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ],
    "has_explicit_shared_members": false,
    "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
Errors
Example: too_many_shared_folder_targets
{
    "error_summary": "too_many_shared_folder_targets/...",
    "error": {
        ".tag": "too_many_shared_folder_targets"
    }
}
Example: too_many_write_operations
{
    "error_summary": "too_many_write_operations/...",
    "error": {
        ".tag": "too_many_write_operations"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
UploadSessionFinishError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
lookup_failed UploadSessionLookupError The session arguments are incorrect; the value explains the reason.
UploadSessionLookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
not_found Void The upload session ID was not found or has expired. Upload sessions are valid for 48 hours.
incorrect_offset UploadSessionOffsetError The 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.
UploadSessionOffsetError
correct_offset UInt64 The offset up to which data has been collected.
closed Void You are attempting to append data to an upload session that has alread been closed (i.e. committed).
not_closed Void The session must be closed before calling upload_session/finish_batch.
path WriteError Unable to save the uploaded contents to a file.
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
too_many_shared_folder_targets Void 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_operations Void There are too many write operations happening in the user's Dropbox. You should retry uploading this file.

/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_v2 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_v2 call.
This route will return a job_id immediately and do the async commit job in background. Use upload_session/finish_batch/check to check the job status.
For the same account, this route should be executed serially. That means you should not start the next job before current job finishes. We allow up to 1000 entries in a single request.

URL Structure
https://api.dropboxapi.com/2/files/upload_session/finish_batch
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/upload_session/finish_batch \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"entries\": [{\"cursor\": {\"session_id\": \"1234faaf0678bcde\",\"offset\": 0},\"commit\": {\"path\": \"/Homework/math/Matrices.txt\",\"mode\": \"add\",\"autorename\": true,\"mute\": false}}]}"
Parameters
{
    "entries": [
        {
            "cursor": {
                "session_id": "1234faaf0678bcde",
                "offset": 0
            },
            "commit": {
                "path": "/Homework/math/Matrices.txt",
                "mode": "add",
                "autorename": true,
                "mute": false
            }
        }
    ]
}
UploadSessionFinishBatchArg
entries List of (UploadSessionFinishArg, max_items=1000) Commit information for each file in the batch.
UploadSessionFinishArg
cursor UploadSessionCursor Contains the upload session ID and the offset.
UploadSessionCursor
session_id String The upload session ID (returned by upload_session/start).
offset UInt64 The amount of data that has been uploaded so far. We use this to make sure upload data isn't lost or duplicated in the event of a network error.
commit CommitInfo Contains the path and other optional modifiers for the commit.
CommitInfo
path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)|(id:.*)") Path in the user's Dropbox to save the file.
mode WriteMode Selects what to do if the file already exists. The default for this union is add.
WriteMode (union)
Your intent when writing a file to some path. This is used to determine what constitutes a conflict and what the autorename strategy is.
In some situations, the conflict behavior is identical: (a) If the target path doesn't refer to anything, the file is always written; no conflict. (b) If the target path refers to a folder, it's always a conflict. (c) If the target path refers to a file with identical contents, nothing gets written; no conflict.
The conflict checking differs in the case where there's a file at the target path with contents different from the contents you're trying to write. The value will be one of the following datatypes:
add Void Do not overwrite an existing file if there is a conflict. The autorename strategy is to append a number to the file name. For example, "document.txt" might become "document (2).txt".
overwrite Void Always overwrite the existing file. The autorename strategy is the same as it is for add.
update String(min_length=9, pattern="[0-9a-f]+") Overwrite if the given "rev" matches the existing file's "rev". The autorename strategy is to append the string "conflicted copy" to the file name. For example, "document.txt" might become "document (conflicted copy).txt" or "document (Panda's conflicted copy).txt".
autorename Boolean If 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.
mute Boolean Normally, 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_groups List of (PropertyGroup)? List of custom properties to add to file. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
Returns
Example: complete
{
    ".tag": "complete",
    "entries": [
        {
            ".tag": "success",
            "name": "Prime_Numbers.txt",
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "client_modified": "2015-05-12T15:50:38Z",
            "server_modified": "2015-05-12T15:50:38Z",
            "rev": "a1c10ce0dd78",
            "size": 7212,
            "path_lower": "/homework/math/prime_numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "sharing_info": {
                "read_only": true,
                "parent_shared_folder_id": "84528192421",
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
            },
            "property_groups": [
                {
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ]
                }
            ],
            "has_explicit_shared_members": false,
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        }
    ]
}
Example: async_job_id
{
    ".tag": "async_job_id",
    "async_job_id": "34g93hh34h04y384084"
}
Example: other
{
    ".tag": "other"
}
UploadSessionFinishBatchLaunch (open union)
Result returned by upload_session/finish_batch that may either launch an asynchronous job or complete synchronously. The value will be one of the following datatypes. New values may be introduced as our API evolves.
async_job_id String(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 UploadSessionFinishBatchResult
UploadSessionFinishBatchResult
entries List of (UploadSessionFinishBatchResultEntry) Commit result for each file in the batch.
UploadSessionFinishBatchResultEntry (union)
The value will be one of the following datatypes:
success FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
failure UploadSessionFinishError
UploadSessionFinishError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
lookup_failed UploadSessionLookupError The session arguments are incorrect; the value explains the reason.
UploadSessionLookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
not_found Void The upload session ID was not found or has expired. Upload sessions are valid for 48 hours.
incorrect_offset UploadSessionOffsetError The 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.
UploadSessionOffsetError
correct_offset UInt64 The offset up to which data has been collected.
closed Void You are attempting to append data to an upload session that has alread been closed (i.e. committed).
not_closed Void The session must be closed before calling upload_session/finish_batch.
path WriteError Unable to save the uploaded contents to a file.
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
too_many_shared_folder_targets Void 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_operations Void There are too many write operations happening in the user's Dropbox. You should retry uploading this file.
Errors

No 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
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/upload_session/finish_batch/check \
    --header "Authorization: Bearer " \
    --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_id String(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",
            "name": "Prime_Numbers.txt",
            "id": "id:a4ayc_80_OEAAAAAAAAAXw",
            "client_modified": "2015-05-12T15:50:38Z",
            "server_modified": "2015-05-12T15:50:38Z",
            "rev": "a1c10ce0dd78",
            "size": 7212,
            "path_lower": "/homework/math/prime_numbers.txt",
            "path_display": "/Homework/math/Prime_Numbers.txt",
            "sharing_info": {
                "read_only": true,
                "parent_shared_folder_id": "84528192421",
                "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
            },
            "property_groups": [
                {
                    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
                    "fields": [
                        {
                            "name": "Security Policy",
                            "value": "Confidential"
                        }
                    ]
                }
            ],
            "has_explicit_shared_members": false,
            "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        }
    ]
}
Example: in_progress
{
    ".tag": "in_progress"
}
UploadSessionFinishBatchJobStatus (union)
The value will be one of the following datatypes:
in_progress Void The asynchronous job is still in progress.
complete UploadSessionFinishBatchResult The upload_session/finish_batch has finished.
UploadSessionFinishBatchResult
entries List of (UploadSessionFinishBatchResultEntry) Commit result for each file in the batch.
UploadSessionFinishBatchResultEntry (union)
The value will be one of the following datatypes:
success FileMetadata
FileMetadata
name String The last component of the path (including extension). This never contains a slash.
id String(min_length=1) A unique identifier for the file.
client_modified Timestamp(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_modified Timestamp(format="%Y-%m-%dT%H:%M:%SZ") The last time the file was modified on Dropbox.
rev String(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.
size UInt64 The 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.
media_info MediaInfo? Additional information if the file is a photo or video. This field is optional.
MediaInfo (union)
The value will be one of the following datatypes:
pending Void Indicate the photo/video is still under processing and metadata is not available yet.
metadata MediaMetadata The metadata for the photo/video.
MediaMetadata (datatype with subtypes)
Metadata for a photo or video. This datatype will be one of the following subtypes:
photo PhotoMetadata
PhotoMetadata
Metadata for a photo.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
video VideoMetadata
VideoMetadata
Metadata for a video.
dimensions Dimensions? Dimension of the photo/video. This field is optional.
Dimensions
Dimensions for a photo or video.
height UInt64 Height of the photo/video.
width UInt64 Width of the photo/video.
location GpsCoordinates? The GPS coordinate of the photo/video. This field is optional.
GpsCoordinates
GPS coordinates for a photo or video.
latitude Float64 Latitude of the GPS coordinates.
longitude Float64 Longitude of the GPS coordinates.
time_taken Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? The timestamp when the photo/video is taken. This field is optional.
duration UInt64? The duration of the video in milliseconds. This field is optional.
sharing_info FileSharingInfo? Set if this file is contained in a shared folder. This field is optional.
FileSharingInfo
Sharing info for a file which is contained by a shared folder.
read_only Boolean True if the file or folder is inside a read-only shared folder.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") ID of shared folder that holds this file.
modified_by String(min_length=40, max_length=40)? The last user who modified the file. This field will be null if the user's account has been deleted. This field is optional.
property_groups List of (PropertyGroup)? Additional information if the file has custom properties with the property template specified. This field is optional.
PropertyGroup
A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate. This datatype comes from an imported namespace originally defined in the file_properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.
fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.
PropertyField
Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup. This datatype comes from an imported namespace originally defined in the file_properties namespace.
name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.
value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.
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.
failure UploadSessionFinishError
UploadSessionFinishError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
lookup_failed UploadSessionLookupError The session arguments are incorrect; the value explains the reason.
UploadSessionLookupError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
not_found Void The upload session ID was not found or has expired. Upload sessions are valid for 48 hours.
incorrect_offset UploadSessionOffsetError The 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.
UploadSessionOffsetError
correct_offset UInt64 The offset up to which data has been collected.
closed Void You are attempting to append data to an upload session that has alread been closed (i.e. committed).
not_closed Void The session must be closed before calling upload_session/finish_batch.
path WriteError Unable to save the uploaded contents to a file.
WriteError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
malformed_path String? This field is optional.
conflict WriteConflictError Couldn't write to the target path because there was something in the way.
WriteConflictError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
file Void There's a file in the way.
folder Void There's a folder in the way.
file_ancestor Void There's a file at an ancestor path, so we couldn't create the required parent folders.
no_write_permission Void The user doesn't have permissions to write to the target location.
insufficient_space Void The user doesn't have enough available space (bytes) to write more data.
disallowed_name Void Dropbox will not save the file or folder because of its name.
team_folder Void This endpoint cannot move or delete team folders.
too_many_shared_folder_targets Void 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_operations Void There are too many write operations happening in the user's Dropbox. You should retry uploading this file.
Errors
Example: invalid_async_job_id
{
    "error_summary": "invalid_async_job_id/...",
    "error": {
        ".tag": "invalid_async_job_id"
    }
}
Example: internal_error
{
    "error_summary": "internal_error/...",
    "error": {
        ".tag": "internal_error"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "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. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_async_job_id Void The job ID is invalid.
internal_error Void Something 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.

/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 MB. This call starts a new upload session with the given data. You can then use upload_session/append_v2 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 MB.
An upload session can be used for a maximum of 48 hours. Attempting to use an UploadSessionStartResult.session_id with upload_session/append_v2 or upload_session/finish more than 48 hours after its creation will return a UploadSessionLookupError.not_found.

URL Structure
https://content.dropboxapi.com/2/files/upload_session/start
Authentication
User Authentication
Endpoint format
Content-upload
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/upload_session/start \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"close\": false}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "close": false
}
UploadSessionStartArg
close Boolean If true, the current session will be closed, at which point you won't be able to call upload_session/append_v2 anymore with the current session. The default for this field is False.
Returns
{
    "session_id": "1234faaf0678bcde"
}
UploadSessionStartResult
session_id String A unique identifier for the upload session. Pass this to upload_session/append_v2 and upload_session/finish.
Errors

No errors.

paper

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

/docs/archive

Description

Marks the given Paper doc as archived.
Note: This action can be performed or undone by anyone with edit permissions to the doc.

URL Structure
https://api.dropboxapi.com/2/paper/docs/archive
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/archive \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
RefPaperDoc
doc_id String The Paper doc ID.
Returns

No return values.

Errors
Example: insufficient_permissions
{
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.

/docs/create

Description

Creates a new Paper doc with the provided content.

URL Structure
https://api.dropboxapi.com/2/paper/docs/create
Authentication
User Authentication
Endpoint format
Content-upload
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/create \
    --header "Authorization: Bearer " \
    --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_format ImportFormat The format of provided data.
ImportFormat (open union)
The import format of the incoming data. The value will be one of the following datatypes. New values may be introduced as our API evolves.
html Void The provided data is interpreted as standard HTML.
markdown Void The provided data is interpreted as markdown.
Note: The first line of the provided document will be used as the doc title.
plain_text Void The provided data is interpreted as plain text.
Note: The first line of the provided document will be used as the doc title.
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_id String Doc ID of the newly created doc.
revision Int64 The Paper doc revision. Simply an ever increasing number.
title String The Paper doc title.
Errors
Example: insufficient_permissions
{
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: content_malformed
{
    "error_summary": "content_malformed/...",
    "error": {
        ".tag": "content_malformed"
    }
}
Example: folder_not_found
{
    "error_summary": "folder_not_found/...",
    "error": {
        ".tag": "folder_not_found"
    }
}
Example: doc_length_exceeded
{
    "error_summary": "doc_length_exceeded/...",
    "error": {
        ".tag": "doc_length_exceeded"
    }
}
Example: image_size_exceeded
{
    "error_summary": "image_size_exceeded/...",
    "error": {
        ".tag": "image_size_exceeded"
    }
}
PaperDocCreateError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
content_malformed Void The provided content was malformed and cannot be imported to Paper.
folder_not_found Void The specified Paper folder is cannot be found.
doc_length_exceeded Void The newly created Paper doc would be too large. Please split the content into multiple docs.
image_size_exceeded Void The imported document contains an image that is too large. The current limit is 1MB. Note: This only applies to HTML with data uri.

/docs/download

Description

Exports and downloads Paper doc either as HTML or markdown.

URL Structure
https://api.dropboxapi.com/2/paper/docs/download
Authentication
User Authentication
Endpoint format
Content-download
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/download \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\",\"export_format\": \"markdown\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "export_format": "markdown"
}
PaperDocExport
doc_id String The Paper doc ID.
export_format ExportFormat
ExportFormat (open union)
The desired export format of the Paper doc. The value will be one of the following datatypes. New values may be introduced as our API evolves.
html Void The HTML export format.
markdown Void The markdown export format.
Returns
{
    "owner": "james@example.com",
    "title": "Week one retention",
    "revision": 456736745,
    "mime_type": "text/x-markdown"
}
PaperDocExportResult
owner String The Paper doc owner's email address.
title String The Paper doc title.
revision Int64 The Paper doc revision. Simply an ever increasing number.
mime_type String MIME type of the export. This corresponds to ExportFormat specified in the request.
Errors
Example: insufficient_permissions
{
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.

/docs/folder_users/list

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.

URL Structure
https://api.dropboxapi.com/2/paper/docs/folder_users/list
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/folder_users/list \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\",\"limit\": 100}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "limit": 100
}
ListUsersOnFolderArgs
doc_id String The Paper doc ID.
limit Int32 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
{
    "invitees": [
        {
            ".tag": "email",
            "email": "jessica@example.com"
        }
    ],
    "users": [
        {
            "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "same_team": true,
            "team_member_id": "dbmid:abcd1234"
        }
    ],
    "cursor": {
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb",
        "expiration": "2016-08-07T14:56:15Z"
    },
    "has_more": false
}
ListUsersOnFolderResponse
invitees List of (InviteeInfo) List of email addresses that are invited on the Paper folder.
InviteeInfo (open union)
Information about the recipient of a shared content invitation. This datatype comes from an imported namespace originally defined in the sharing namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") E-mail address of invited user.
users List of (UserInfo) List of users that are invited on the Paper folder.
UserInfo
Basic information about a user. Use users.get_account and users.get_account_batch to obtain more detailed information. This datatype comes from an imported namespace originally defined in the sharing namespace.
account_id String(min_length=40, max_length=40) The account ID of the user.
same_team Boolean If the user is in the same team as current user.
team_member_id String? The team member ID of the shared folder member. Only present if same_team is true. This field is optional.
cursor Cursor Pass 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.
Cursor
value String The actual cursor value.
expiration Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? Expiration time of value.
Some cursors might have expiration time assigned. This is a UTC value after which the cursor is no longer valid and the API starts returning an error. If cursor expires a new one needs to be obtained and pagination needs to be restarted. Some cursors might be short-lived some cursors might be long-lived.
This really depends on the sorting type and order, e.g.:
1. on one hand, listing docs created by the user, sorted by the created time ascending will have undefinite expiration because the results cannot change while the iteration is happening. This cursor would be suitable for long term polling.
2. on the other hand, listing docs sorted by the last modified time will have a very short expiration as docs do get modified very often and the modified time can be changed while the iteration is happening thus altering the results. This field is optional.
has_more Boolean Will 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_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.

/docs/folder_users/list/continue

Description

Once a cursor has been retrieved from docs/folder_users/list, use this to paginate through all users on the Paper folder.

URL Structure
https://api.dropboxapi.com/2/paper/docs/folder_users/list/continue
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/folder_users/list/continue \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\",\"cursor\": \"U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "cursor": "U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd"
}
ListUsersOnFolderContinueArgs
doc_id String The Paper doc ID.
cursor String The cursor obtained from docs/folder_users/list or docs/folder_users/list/continue. Allows for pagination.
Returns
{
    "invitees": [
        {
            ".tag": "email",
            "email": "jessica@example.com"
        }
    ],
    "users": [
        {
            "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
            "same_team": true,
            "team_member_id": "dbmid:abcd1234"
        }
    ],
    "cursor": {
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb",
        "expiration": "2016-08-07T14:56:15Z"
    },
    "has_more": false
}
ListUsersOnFolderResponse
invitees List of (InviteeInfo) List of email addresses that are invited on the Paper folder.
InviteeInfo (open union)
Information about the recipient of a shared content invitation. This datatype comes from an imported namespace originally defined in the sharing namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") E-mail address of invited user.
users List of (UserInfo) List of users that are invited on the Paper folder.
UserInfo
Basic information about a user. Use users.get_account and users.get_account_batch to obtain more detailed information. This datatype comes from an imported namespace originally defined in the sharing namespace.
account_id String(min_length=40, max_length=40) The account ID of the user.
same_team Boolean If the user is in the same team as current user.
team_member_id String? The team member ID of the shared folder member. Only present if same_team is true. This field is optional.
cursor Cursor Pass 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.
Cursor
value String The actual cursor value.
expiration Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? Expiration time of value.
Some cursors might have expiration time assigned. This is a UTC value after which the cursor is no longer valid and the API starts returning an error. If cursor expires a new one needs to be obtained and pagination needs to be restarted. Some cursors might be short-lived some cursors might be long-lived.
This really depends on the sorting type and order, e.g.:
1. on one hand, listing docs created by the user, sorted by the created time ascending will have undefinite expiration because the results cannot change while the iteration is happening. This cursor would be suitable for long term polling.
2. on the other hand, listing docs sorted by the last modified time will have a very short expiration as docs do get modified very often and the modified time can be changed while the iteration is happening thus altering the results. This field is optional.
has_more Boolean Will 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_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
ListUsersCursorError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.
cursor_error PaperApiCursorError
PaperApiCursorError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
expired_cursor Void The provided cursor is expired.
invalid_cursor Void The provided cursor is invalid.
wrong_user_in_cursor Void The provided cursor contains invalid user.
reset Void Indicates that the cursor has been invalidated. Call the corresponding non-continue endpoint to obtain a new cursor.

/docs/get_folder_info

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.

Note: If the Paper doc is not in any folder (aka unfiled) the response will be empty.

URL Structure
https://api.dropboxapi.com/2/paper/docs/get_folder_info
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/get_folder_info \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
RefPaperDoc
doc_id String The Paper doc ID.
Returns
{
    "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 FolderSharingPolicyType? The sharing policy of the folder containing the Paper doc. This field is optional.
FolderSharingPolicyType (union)
The sharing policy of a Paper folder.

Note: The sharing policy of subfolders is inherited from the root folder. The value will be one of the following datatypes:
team Void Everyone in your team and anyone directly invited can access this folder.
invite_only Void Only people directly invited can access this folder.
folders List of (Folder)? The folder path. If present the first folder is the root folder. This field is optional.
Folder
Data structure representing a Paper folder.
id String Paper folder ID. This ID uniquely identifies the folder.
name String Paper folder name.
Errors
Example: insufficient_permissions
{
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.

/docs/list

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.

URL Structure
https://api.dropboxapi.com/2/paper/docs/list
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/list \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"filter_by\": \"docs_created\",\"sort_by\": \"modified\",\"sort_order\": \"descending\",\"limit\": 100}"
Parameters
{
    "filter_by": "docs_created",
    "sort_by": "modified",
    "sort_order": "descending",
    "limit": 100
}
ListPaperDocsArgs
filter_by ListPaperDocsFilterBy Allows user to specify how the Paper docs should be filtered. The default for this union is docs_accessed.
ListPaperDocsFilterBy (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
docs_accessed Void Fetches all Paper doc IDs that the user has ever accessed.
docs_created Void Fetches only the Paper doc IDs that the user has created.
sort_by ListPaperDocsSortBy Allows user to specify how the Paper docs should be sorted. The default for this union is accessed.
ListPaperDocsSortBy (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
accessed Void Sorts the Paper docs by the time they were last accessed.
modified Void Sorts the Paper docs by the time they were last modified.
created Void Sorts the Paper docs by the creation time.
sort_order ListPaperDocsSortOrder Allows user to specify the sort order of the result. The default for this union is ascending.
ListPaperDocsSortOrder (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
ascending Void Sorts the search result in ascending order.
descending Void Sorts the search result in descending order.
limit Int32 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.
Returns
{
    "doc_ids": [
        "zO1E7coc54sE8IuMdUoxz",
        "mm1AmDgVyZ10zf7qb0qzn",
        "dByYHZvTPBnXilGgyc5mm"
    ],
    "cursor": {
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb",
        "expiration": "2016-08-07T14:56:15Z"
    },
    "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.
cursor Cursor Pass 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.
Cursor
value String The actual cursor value.
expiration Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? Expiration time of value.
Some cursors might have expiration time assigned. This is a UTC value after which the cursor is no longer valid and the API starts returning an error. If cursor expires a new one needs to be obtained and pagination needs to be restarted. Some cursors might be short-lived some cursors might be long-lived.
This really depends on the sorting type and order, e.g.:
1. on one hand, listing docs created by the user, sorted by the created time ascending will have undefinite expiration because the results cannot change while the iteration is happening. This cursor would be suitable for long term polling.
2. on the other hand, listing docs sorted by the last modified time will have a very short expiration as docs do get modified very often and the modified time can be changed while the iteration is happening thus altering the results. This field is optional.
has_more Boolean Will 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 errors.

/docs/list/continue

Description

Once a cursor has been retrieved from docs/list, use this to paginate through all Paper doc.

URL Structure
https://api.dropboxapi.com/2/paper/docs/list/continue
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/list/continue \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"cursor\": \"U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd\"}"
Parameters
{
    "cursor": "U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd"
}
ListPaperDocsContinueArgs
cursor String The cursor obtained from docs/list or docs/list/continue. Allows for pagination.
Returns
{
    "doc_ids": [
        "zO1E7coc54sE8IuMdUoxz",
        "mm1AmDgVyZ10zf7qb0qzn",
        "dByYHZvTPBnXilGgyc5mm"
    ],
    "cursor": {
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb",
        "expiration": "2016-08-07T14:56:15Z"
    },
    "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.
cursor Cursor Pass 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.
Cursor
value String The actual cursor value.
expiration Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? Expiration time of value.
Some cursors might have expiration time assigned. This is a UTC value after which the cursor is no longer valid and the API starts returning an error. If cursor expires a new one needs to be obtained and pagination needs to be restarted. Some cursors might be short-lived some cursors might be long-lived.
This really depends on the sorting type and order, e.g.:
1. on one hand, listing docs created by the user, sorted by the created time ascending will have undefinite expiration because the results cannot change while the iteration is happening. This cursor would be suitable for long term polling.
2. on the other hand, listing docs sorted by the last modified time will have a very short expiration as docs do get modified very often and the modified time can be changed while the iteration is happening thus altering the results. This field is optional.
has_more Boolean Will 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
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
ListDocsCursorError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
cursor_error PaperApiCursorError
PaperApiCursorError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
expired_cursor Void The provided cursor is expired.
invalid_cursor Void The provided cursor is invalid.
wrong_user_in_cursor Void The provided cursor contains invalid user.
reset Void Indicates that the cursor has been invalidated. Call the corresponding non-continue endpoint to obtain a new cursor.

/docs/permanently_delete

Description

Permanently deletes the given Paper doc. This operation is final as the doc cannot be recovered.

Note: This action can be performed only by the doc owner.

URL Structure
https://api.dropboxapi.com/2/paper/docs/permanently_delete
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/permanently_delete \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
RefPaperDoc
doc_id String The Paper doc ID.
Returns

No return values.

Errors
Example: insufficient_permissions
{
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.

/docs/sharing_policy/get

Description

Gets the default sharing policy for the given Paper doc.

URL Structure
https://api.dropboxapi.com/2/paper/docs/sharing_policy/get
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/sharing_policy/get \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q"
}
RefPaperDoc
doc_id String The Paper doc ID.
Returns
{
    "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 SharingPublicPolicyType? This value applies to the non-team members. This field is optional.
SharingPublicPolicyType (union)
The value will be one of the following datatypes:
people_with_link_can_edit Void Users who have a link to this doc can edit it.
people_with_link_can_view_and_comment Void Users who have a link to this doc can view and comment on it.
invite_only Void Users must be explicitly invited to this doc.
disabled Void Value used to indicate that doc sharing is enabled only within team.
team_sharing_policy SharingTeamPolicyType? This value applies to the team members only. The value is null for all personal accounts. This field is optional.
SharingTeamPolicyType (union)
The sharing policy type of the Paper doc. The value will be one of the following datatypes:
people_with_link_can_edit Void Users who have a link to this doc can edit it.
people_with_link_can_view_and_comment Void Users who have a link to this doc can view and comment on it.
invite_only Void Users must be explicitly invited to this doc.
Errors
Example: insufficient_permissions
{
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.

/docs/sharing_policy/set

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.

Note: 'public_sharing_policy' cannot be set to the value 'disabled' because this setting can be changed only via the team admin console.

URL Structure
https://api.dropboxapi.com/2/paper/docs/sharing_policy/set
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/sharing_policy/set \
    --header "Authorization: Bearer " \
    --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_id String The Paper doc ID.
sharing_policy SharingPolicy The default sharing policy to be set for the Paper doc.
SharingPolicy
Sharing policy of Paper doc.
public_sharing_policy SharingPublicPolicyType? This value applies to the non-team members. This field is optional.
SharingPublicPolicyType (union)
The value will be one of the following datatypes:
people_with_link_can_edit Void Users who have a link to this doc can edit it.
people_with_link_can_view_and_comment Void Users who have a link to this doc can view and comment on it.
invite_only Void Users must be explicitly invited to this doc.
disabled Void Value used to indicate that doc sharing is enabled only within team.
team_sharing_policy SharingTeamPolicyType? This value applies to the team members only. The value is null for all personal accounts. This field is optional.
SharingTeamPolicyType (union)
The sharing policy type of the Paper doc. The value will be one of the following datatypes:
people_with_link_can_edit Void Users who have a link to this doc can edit it.
people_with_link_can_view_and_comment Void Users who have a link to this doc can view and comment on it.
invite_only Void Users must be explicitly invited to this doc.
Returns

No return values.

Errors
Example: insufficient_permissions
{
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.

/docs/update

Description

Updates an existing Paper doc with the provided content.

URL Structure
https://api.dropboxapi.com/2/paper/docs/update
Authentication
User Authentication
Endpoint format
Content-upload
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/update \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\",\"doc_update_policy\": \"overwrite_all\",\"revision\": 12345,\"import_format\": \"html\"}" \
    --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",
    "revision": 12345,
    "import_format": "html"
}
Example: Prepend the content into the doc (the doc title will remain unchanged).
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "doc_update_policy": "prepend",
    "revision": 56556,
    "import_format": "plain_text"
}
PaperDocUpdateArgs
doc_id String The Paper doc ID.
doc_update_policy PaperDocUpdatePolicy The policy used for the current update call.
PaperDocUpdatePolicy (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
append Void The content will be appended to the doc.
prepend Void The content will be prepended to the doc.
Note: the doc title will not be affected.
overwrite_all Void The document will be overwitten at the head with the provided content.
revision Int64 The latest doc revision. This value must match the head revision or an error code will be returned. This is to prevent colliding writes.
import_format ImportFormat The format of provided data.
ImportFormat (open union)
The import format of the incoming data. The value will be one of the following datatypes. New values may be introduced as our API evolves.
html Void The provided data is interpreted as standard HTML.
markdown Void The provided data is interpreted as markdown.
Note: The first line of the provided document will be used as the doc title.
plain_text Void The provided data is interpreted as plain text.
Note: The first line of the provided document will be used as the doc title.
Returns
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "revision": 456736745,
    "title": "Week one retention"
}
PaperDocCreateUpdateResult
doc_id String Doc ID of the newly created doc.
revision Int64 The Paper doc revision. Simply an ever increasing number.
title String The Paper doc title.
Errors
Example: insufficient_permissions
{
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
Example: content_malformed
{
    "error_summary": "content_malformed/...",
    "error": {
        ".tag": "content_malformed"
    }
}
Example: revision_mismatch
{
    "error_summary": "revision_mismatch/...",
    "error": {
        ".tag": "revision_mismatch"
    }
}
Example: doc_length_exceeded
{
    "error_summary": "doc_length_exceeded/...",
    "error": {
        ".tag": "doc_length_exceeded"
    }
}
Example: image_size_exceeded
{
    "error_summary": "image_size_exceeded/...",
    "error": {
        ".tag": "image_size_exceeded"
    }
}
Example: doc_archived
{
    "error_summary": "doc_archived/...",
    "error": {
        ".tag": "doc_archived"
    }
}
Example: doc_deleted
{
    "error_summary": "doc_deleted/...",
    "error": {
        ".tag": "doc_deleted"
    }
}
PaperDocUpdateError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.
content_malformed Void The provided content was malformed and cannot be imported to Paper.
revision_mismatch Void The provided revision does not match the document head.
doc_length_exceeded Void The newly created Paper doc would be too large, split the content into multiple docs.
image_size_exceeded Void The imported document contains an image that is too large. The current limit is 1MB. Note: This only applies to HTML with data uri.
doc_archived Void This operation is not allowed on archived Paper docs.
doc_deleted Void This operation is not allowed on deleted Paper docs.

/docs/users/add

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.

Note: The Doc owner's permissions cannot be changed.

URL Structure
https://api.dropboxapi.com/2/paper/docs/users/add
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/users/add \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\",\"members\": [{\"member\": {\".tag\": \"email\",\"email\": \"justin@example.com\"},\"permission_level\": \"view_and_comment\"}],\"custom_message\": \"Welcome to Paper.\",\"quiet\": false}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "members": [
        {
            "member": {
                ".tag": "email",
                "email": "justin@example.com"
            },
            "permission_level": "view_and_comment"
        }
    ],
    "custom_message": "Welcome to Paper.",
    "quiet": false
}
AddPaperDocUser
doc_id String The Paper doc ID.
members List of (AddMember, max_items=20) User which should be added to the Paper doc. Specify only email address or Dropbox account ID.
AddMember
member MemberSelector User which should be added to the Paper doc. Specify only email address or Dropbox account ID.
MemberSelector (open union)
Includes different ways to identify a member of a shared folder. This datatype comes from an imported namespace originally defined in the sharing namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
dropbox_id String(min_length=1) Dropbox account, team member, or group ID of member.
email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") E-mail address of member.
permission_level PaperDocPermissionLevel Permission for the user. The default for this union is edit.
PaperDocPermissionLevel (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
edit Void User will be granted edit permissions.
view_and_comment Void User will be granted view and comment permissions.
custom_message String? A personal message that will be emailed to each successfully added member. This field is optional.
quiet Boolean Clients should set this to true if no email message shall be sent to added users. The default for this field is False.
Returns
This route returns a list. This means the route can accept a homogenous list of the following types:
AddPaperDocUserMemberResult
Per-member result for docs/users/add.
member MemberSelector One of specified input members.
MemberSelector (open union)
Includes different ways to identify a member of a shared folder. This datatype comes from an imported namespace originally defined in the sharing namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
dropbox_id String(min_length=1) Dropbox account, team member, or group ID of member.
email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") E-mail address of member.
result AddPaperDocUserResult The outcome of the action on this member.
AddPaperDocUserResult (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
success Void User was successfully added to the Paper doc.
unknown_error Void Something unexpected happened when trying to add the user to the Paper doc.
sharing_outside_team_disabled Void The Paper doc can be shared only with team members.
daily_limit_reached Void The daily limit of how many users can be added to the Paper doc was reached.
user_is_owner Void Owner's permissions cannot be changed.
failed_user_data_retrieval Void User data could not be retrieved. Clients should retry.
permission_already_granted Void This user already has the correct permission to the Paper doc.
Errors
Example: insufficient_permissions
{
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.

/docs/users/list

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.

URL Structure
https://api.dropboxapi.com/2/paper/docs/users/list
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/users/list \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\",\"limit\": 100,\"filter_by\": \"shared\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "limit": 100,
    "filter_by": "shared"
}
ListUsersOnPaperDocArgs
doc_id String The Paper doc ID.
limit Int32 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_by UserOnPaperDocFilter Specify this attribute if you want to obtain users that have already accessed the Paper doc. The default for this union is shared.
UserOnPaperDocFilter (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
visited Void all users who have visited the Paper doc.
shared Void All uses who are shared on the Paper doc. This includes all users who have visited the Paper doc as well as those who have not.
Returns
{
    "invitees": [
        {
            "invitee": {
                ".tag": "email",
                "email": "jessica@example.com"
            },
            "permission_level": {
                ".tag": "edit"
            }
        }
    ],
    "users": [
        {
            "user": {
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "same_team": true,
                "team_member_id": "dbmid:abcd1234"
            },
            "permission_level": {
                ".tag": "view_and_comment"
            }
        }
    ],
    "doc_owner": {
        "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "same_team": true,
        "team_member_id": "dbmid:abcd1234"
    },
    "cursor": {
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb",
        "expiration": "2016-08-07T14:56:15Z"
    },
    "has_more": false
}
ListUsersOnPaperDocResponse
invitees List of (InviteeInfoWithPermissionLevel) List of email addresses with their respective permission levels that are invited on the Paper doc.
InviteeInfoWithPermissionLevel
invitee InviteeInfo Email address invited to the Paper doc.
InviteeInfo (open union)
Information about the recipient of a shared content invitation. This datatype comes from an imported namespace originally defined in the sharing namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") E-mail address of invited user.
permission_level PaperDocPermissionLevel Permission level for the invitee.
PaperDocPermissionLevel (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
edit Void User will be granted edit permissions.
view_and_comment Void User will be granted view and comment permissions.
users List of (UserInfoWithPermissionLevel) List of users with their respective permission levels that are invited on the Paper folder.
UserInfoWithPermissionLevel
user UserInfo User shared on the Paper doc.
UserInfo
Basic information about a user. Use users.get_account and users.get_account_batch to obtain more detailed information. This datatype comes from an imported namespace originally defined in the sharing namespace.
account_id String(min_length=40, max_length=40) The account ID of the user.
same_team Boolean If the user is in the same team as current user.
team_member_id String? The team member ID of the shared folder member. Only present if same_team is true. This field is optional.
permission_level PaperDocPermissionLevel Permission level for the user.
PaperDocPermissionLevel (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
edit Void User will be granted edit permissions.
view_and_comment Void User will be granted view and comment permissions.
doc_owner UserInfo The Paper doc owner. This field is populated on every single response.
UserInfo
Basic information about a user. Use users.get_account and users.get_account_batch to obtain more detailed information. This datatype comes from an imported namespace originally defined in the sharing namespace.
account_id String(min_length=40, max_length=40) The account ID of the user.
same_team Boolean If the user is in the same team as current user.
team_member_id String? The team member ID of the shared folder member. Only present if same_team is true. This field is optional.
cursor Cursor Pass 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.
Cursor
value String The actual cursor value.
expiration Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? Expiration time of value.
Some cursors might have expiration time assigned. This is a UTC value after which the cursor is no longer valid and the API starts returning an error. If cursor expires a new one needs to be obtained and pagination needs to be restarted. Some cursors might be short-lived some cursors might be long-lived.
This really depends on the sorting type and order, e.g.:
1. on one hand, listing docs created by the user, sorted by the created time ascending will have undefinite expiration because the results cannot change while the iteration is happening. This cursor would be suitable for long term polling.
2. on the other hand, listing docs sorted by the last modified time will have a very short expiration as docs do get modified very often and the modified time can be changed while the iteration is happening thus altering the results. This field is optional.
has_more Boolean Will 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_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.

/docs/users/list/continue

Description

Once a cursor has been retrieved from docs/users/list, use this to paginate through all users on the Paper doc.

URL Structure
https://api.dropboxapi.com/2/paper/docs/users/list/continue
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/users/list/continue \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"doc_id\": \"uaSvRuxvnkFa12PTkBv5q\",\"cursor\": \"U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd\"}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "cursor": "U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd"
}
ListUsersOnPaperDocContinueArgs
doc_id String The Paper doc ID.
cursor String The cursor obtained from docs/users/list or docs/users/list/continue. Allows for pagination.
Returns
{
    "invitees": [
        {
            "invitee": {
                ".tag": "email",
                "email": "jessica@example.com"
            },
            "permission_level": {
                ".tag": "edit"
            }
        }
    ],
    "users": [
        {
            "user": {
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "same_team": true,
                "team_member_id": "dbmid:abcd1234"
            },
            "permission_level": {
                ".tag": "view_and_comment"
            }
        }
    ],
    "doc_owner": {
        "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "same_team": true,
        "team_member_id": "dbmid:abcd1234"
    },
    "cursor": {
        "value": "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb",
        "expiration": "2016-08-07T14:56:15Z"
    },
    "has_more": false
}
ListUsersOnPaperDocResponse
invitees List of (InviteeInfoWithPermissionLevel) List of email addresses with their respective permission levels that are invited on the Paper doc.
InviteeInfoWithPermissionLevel
invitee InviteeInfo Email address invited to the Paper doc.
InviteeInfo (open union)
Information about the recipient of a shared content invitation. This datatype comes from an imported namespace originally defined in the sharing namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") E-mail address of invited user.
permission_level PaperDocPermissionLevel Permission level for the invitee.
PaperDocPermissionLevel (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
edit Void User will be granted edit permissions.
view_and_comment Void User will be granted view and comment permissions.
users List of (UserInfoWithPermissionLevel) List of users with their respective permission levels that are invited on the Paper folder.
UserInfoWithPermissionLevel
user UserInfo User shared on the Paper doc.
UserInfo
Basic information about a user. Use users.get_account and users.get_account_batch to obtain more detailed information. This datatype comes from an imported namespace originally defined in the sharing namespace.
account_id String(min_length=40, max_length=40) The account ID of the user.
same_team Boolean If the user is in the same team as current user.
team_member_id String? The team member ID of the shared folder member. Only present if same_team is true. This field is optional.
permission_level PaperDocPermissionLevel Permission level for the user.
PaperDocPermissionLevel (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
edit Void User will be granted edit permissions.
view_and_comment Void User will be granted view and comment permissions.
doc_owner UserInfo The Paper doc owner. This field is populated on every single response.
UserInfo
Basic information about a user. Use users.get_account and users.get_account_batch to obtain more detailed information. This datatype comes from an imported namespace originally defined in the sharing namespace.
account_id String(min_length=40, max_length=40) The account ID of the user.
same_team Boolean If the user is in the same team as current user.
team_member_id String? The team member ID of the shared folder member. Only present if same_team is true. This field is optional.
cursor Cursor Pass 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.
Cursor
value String The actual cursor value.
expiration Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? Expiration time of value.
Some cursors might have expiration time assigned. This is a UTC value after which the cursor is no longer valid and the API starts returning an error. If cursor expires a new one needs to be obtained and pagination needs to be restarted. Some cursors might be short-lived some cursors might be long-lived.
This really depends on the sorting type and order, e.g.:
1. on one hand, listing docs created by the user, sorted by the created time ascending will have undefinite expiration because the results cannot change while the iteration is happening. This cursor would be suitable for long term polling.
2. on the other hand, listing docs sorted by the last modified time will have a very short expiration as docs do get modified very often and the modified time can be changed while the iteration is happening thus altering the results. This field is optional.
has_more Boolean Will 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_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
ListUsersCursorError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.
cursor_error PaperApiCursorError
PaperApiCursorError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
expired_cursor Void The provided cursor is expired.
invalid_cursor Void The provided cursor is invalid.
wrong_user_in_cursor Void The provided cursor contains invalid user.
reset Void Indicates that the cursor has been invalidated. Call the corresponding non-continue endpoint to obtain a new cursor.

/docs/users/remove

Description

Allows an owner or editor to remove users from a Paper doc using their email address or Dropbox account ID.

Note: Doc owner cannot be removed.

URL Structure
https://api.dropboxapi.com/2/paper/docs/users/remove
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/paper/docs/users/remove \
    --header "Authorization: Bearer " \
    --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_id String The Paper doc ID.
member MemberSelector User which should be removed from the Paper doc. Specify only email address or Dropbox account ID.
MemberSelector (open union)
Includes different ways to identify a member of a shared folder. This datatype comes from an imported namespace originally defined in the sharing namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
dropbox_id String(min_length=1) Dropbox account, team member, or group ID of member.
email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") E-mail address of member.
Returns

No return values.

Errors
Example: insufficient_permissions
{
    "error_summary": "insufficient_permissions/...",
    "error": {
        ".tag": "insufficient_permissions"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
Example: doc_not_found
{
    "error_summary": "doc_not_found/...",
    "error": {
        ".tag": "doc_not_found"
    }
}
DocLookupError (union)
The value will be one of the following datatypes:
insufficient_permissions Void Your account does not have permissions to perform this action.
doc_not_found Void The required doc was not found.

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.

URL Structure
https://api.dropboxapi.com/2/sharing/add_file_member
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/add_file_member \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"file\": \"id:3kmLmQFnf1AAAAAAAAAAAw\",\"members\": [{\".tag\": \"email\",\"email\": \"justin@example.com\"}],\"custom_message\": \"This is a custom message about ACME.doc\",\"quiet\": false,\"access_level\": \"viewer\",\"add_message_as_comment\": false}"
Parameters
{
    "file": "id:3kmLmQFnf1AAAAAAAAAAAw",
    "members": [
        {
            ".tag": "email",
            "email": "justin@example.com"
        }
    ],
    "custom_message": "This is a custom message about ACME.doc",
    "quiet": false,
    "access_level": "viewer",
    "add_message_as_comment": false
}
AddFileMemberArgs
Arguments for add_file_member.
file String(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?") File to which to add members.
members List of (MemberSelector) Members to add. Note that even an email address is given, this may result in a user being directy added to the membership if that email is the user's main account email.
MemberSelector (open union)
Includes different ways to identify a member of a shared folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
dropbox_id String(min_length=1) Dropbox account, team member, or group ID of member.
email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") E-mail address of member.
custom_message String? Message to send to added members in their invitation. This field is optional.
quiet Boolean Whether added members should be notified via device notifications of their invitation. The default for this field is False.
access_level AccessLevel AccessLevel union object, describing what access level we want to give new members. The default for this union is viewer.
AccessLevel (open union)
Defines the access levels for collaborators. The value will be one of the following datatypes. New values may be introduced as our API evolves.
owner Void The collaborator is the owner of the shared folder. Owners can view and edit the shared folder as well as set the folder's policies using update_folder_policy.
editor Void The collaborator can both view and edit the shared folder.
viewer Void The collaborator can only view the shared folder.
viewer_no_comment Void The collaborator can only view the shared folder and does not have any access to comments.
add_message_as_commentdeprecated Boolean Field is deprecated. If the custom message should be added as a comment on the file. The default for this field is False.
Returns
This route returns a list. This means the route can accept a homogenous list of the following types:
FileMemberActionResult
Per-member result for add_file_member or change_file_member_access.
member MemberSelector One of specified input members.
MemberSelector (open union)
Includes different ways to identify a member of a shared folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
dropbox_id String(min_length=1) Dropbox account, team member, or group ID of member.
email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") E-mail address of member.
result FileMemberActionIndividualResult The outcome of the action on this member.
FileMemberActionIndividualResult (union)
The value will be one of the following datatypes:
success AccessLevel? Member was successfully removed from this file. If AccessLevel is given, the member still has access via a parent shared folder. This field is optional.
AccessLevel (open union)
Defines the access levels for collaborators. The value will be one of the following datatypes. New values may be introduced as our API evolves.
owner Void The collaborator is the owner of the shared folder. Owners can view and edit the shared folder as well as set the folder's policies using update_folder_policy.
editor Void The collaborator can both view and edit the shared folder.
viewer Void The collaborator can only view the shared folder.
viewer_no_comment Void The collaborator can only view the shared folder and does not have any access to comments.
member_error FileMemberActionError User was not able to perform this action.
FileMemberActionError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_member Void Specified member was not found.
no_permission Void User does not have permission to perform this action on this member.
access_error SharingFileAccessError Specified file was invalid or user does not have access.
SharingFileAccessError (open union)
User could not access this file. The value will be one of the following datatypes. New values may be introduced as our API evolves.
no_permission Void Current user does not have sufficient privileges to perform the desired action.
invalid_file Void File specified was not found.
is_folder Void A folder can't be shared this way. Use folder sharing or a shared link instead.
inside_public_folder Void A file inside a public folder can't be shared this way. Use a public link instead.
inside_osx_package Void A Mac OS X package can't be shared this way. Use a shared link instead.
no_explicit_access MemberAccessLevelResult The 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.
MemberAccessLevelResult
Contains information about a member's access level to content after an operation.
access_level AccessLevel? The member still has this level of access to the content through a parent folder. This field is optional.
AccessLevel (open union)
Defines the access levels for collaborators. The value will be one of the following datatypes. New values may be introduced as our API evolves.
owner Void The collaborator is the owner of the shared folder. Owners can view and edit the shared folder as well as set the folder's policies using update_folder_policy.
editor Void The collaborator can both view and edit the shared folder.
viewer Void The collaborator can only view the shared folder.
viewer_no_comment Void The collaborator can only view the shared folder and does not have any access to comments.
warning String? A localized string with additional information about why the user has this access level to the content. This field is optional.
access_details List of (ParentFolderAccessInfo)? 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.
ParentFolderAccessInfo
Contains information about a parent folder that a member has access to.
folder_name String Display name for the folder.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") The identifier of the parent shared folder.
permissions List of (MemberPermission) The user's permissions for the parent shared folder.
MemberPermission
Whether the user is allowed to take the action on the associated member.
action MemberAction The action that the user may wish to take on the member.
MemberAction (open union)
Actions that may be taken on members of a shared folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
leave_a_copy Void Allow the member to keep a copy of the folder when removing.
make_editor Void Make the member an editor of the folder.
make_owner Void Make the member an owner of the folder.
make_viewer Void Make the member a viewer of the folder.
make_viewer_no_comment Void Make the member a viewer of the folder without commenting permissions.
remove Void Remove the member from the folder.
allow Boolean True if the user is allowed to take the action.
reason PermissionDeniedReason? The reason why the user is denied the permission. Not present if the action is allowed. This field is optional.
PermissionDeniedReason (open union)
Possible reasons the user is denied a permission. The value will be one of the following datatypes. New values may be introduced as our API evolves.
user_not_same_team_as_owner Void User is not on the same team as the folder owner.
user_not_allowed_by_owner Void User is prohibited by the owner from taking the action.
target_is_indirect_member Void Target is indirectly a member of the folder, for example by being part of a group.
target_is_owner Void Target is the owner of the folder.
target_is_self Void Target is the user itself.
target_not_active Void Target is not an active member of the team.
folder_is_limited_team_folder Void Folder is team folder for a limited team.
owner_not_on_team Void The content owner needs to be on a Dropbox team to perform this action.
permission_denied Void The user does not have permission to perform this action on the link.
restricted_by_team Void The user's team policy prevents performing this action on the link.
user_account_type Void The user's account type does not support this action.
user_not_on_team Void The user needs to be on a Dropbox team to perform this action.
folder_is_inside_shared_folder Void Folder is inside of another shared folder.
restricted_by_parent_folder Void Policy cannot be changed due to restrictions from parent folder.
insufficient_plan InsufficientPlan
InsufficientPlan
message String A message to tell the user to upgrade in order to support expected action.
upsell_url String? A URL to send the user to in order to obtain the account type they need, e.g. upgrading. Absent if there is no action the user can take to upgrade. This field is optional.
path String The full path to the parent shared folder relative to the acting user's root.
Errors
Example: rate_limit
{
    "error_summary": "rate_limit/...",
    "error": {
        ".tag": "rate_limit"
    }
}
Example: invalid_comment
{
    "error_summary": "invalid_comment/...",
    "error": {
        ".tag": "invalid_comment"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
AddFileMemberError (open union)
Errors for add_file_member. The value will be one of the following datatypes. New values may be introduced as our API evolves.
user_error SharingUserError
SharingUserError (open union)
User account had a problem preventing this action. The value will be one of the following datatypes. New values may be introduced as our API evolves.
email_unverified Void The current user must verify the account e-mail address before performing this action.
access_error SharingFileAccessError
SharingFileAccessError (open union)
User could not access this file. The value will be one of the following datatypes. New values may be introduced as our API evolves.
no_permission Void Current user does not have sufficient privileges to perform the desired action.
invalid_file Void File specified was not found.
is_folder Void A folder can't be shared this way. Use folder sharing or a shared link instead.
inside_public_folder Void A file inside a public folder can't be shared this way. Use a public link instead.
inside_osx_package Void A Mac OS X package can't be shared this way. Use a shared link instead.
rate_limit Void The user has reached the rate limit for invitations.
invalid_comment Void The custom message did not pass comment permissions checks.

/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.
Apps must have full Dropbox access to use this endpoint.

URL Structure
https://api.dropboxapi.com/2/sharing/add_folder_member
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/add_folder_member \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"shared_folder_id\": \"84528192421\",\"members\": [{\"member\": {\".tag\": \"email\",\"email\": \"justin@example.com\"},\"access_level\": \"editor\"},{\"member\": {\".tag\": \"dropbox_id\",\"dropbox_id\": \"dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q\"},\"access_level\": \"viewer\"}],\"quiet\": false,\"custom_message\": \"Documentation for launch day\"}"
Parameters
{
    "shared_folder_id": "84528192421",
    "members": [
        {
            "member": {
                ".tag": "email",
                "email": "justin@example.com"
            },
            "access_level": "editor"
        },
        {
            "member": {
                ".tag": "dropbox_id",
                "dropbox_id": "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"
            },
            "access_level": "viewer"
        }
    ],
    "quiet": false,
    "custom_message": "Documentation for launch day"
}
AddFolderMemberArg
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") The ID for the shared folder.
members List of (AddMember) The intended list of members to add. Added members will receive invites to join the shared folder.
AddMember
The member and type of access the member should have when added to a shared folder.
member MemberSelector The member to add to the shared folder.
MemberSelector (open union)
Includes different ways to identify a member of a shared folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
dropbox_id String(min_length=1) Dropbox account, team member, or group ID of member.
email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") E-mail address of member.
access_level AccessLevel<