Dropbox for HTTP Developers

auth

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.

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.

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.
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 have a reason field with one of the following values:
too_many_requests Void Your app has been making too many requests in the past few minutes.
too_many_write_operations Void There are too many write operations happening in the user's Dropbox. This is also known as "lock contention". You can find more information in the data ingress guide.
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 access token for:
curl -X POST https://api.dropboxapi.com/2/auth/token/from_oauth1 \
    --header "Authorization: Bearer " \
    --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.

files

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

/alpha/get_metadata

PREVIEW - may change or disappear without notice
Description

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

URL Structure
https://api.dropboxapi.com/2/files/alpha/get_metadata
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/alpha/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
}
AlphaGetMetadataArg
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_templates List of (String(min_length=1, pattern="(/|ptid:).*"))? If set to a valid list of template IDs, FileMetadata.property_groups is set for files with custom properties. This field is optional.
Returns
{
    ".tag": "file",
    "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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
Errors
AlphaGetMetadataError (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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
properties_error LookUpPropertiesError
LookUpPropertiesError (union)
The value will be one of the following datatypes:
property_group_not_found Void This property group does not exist for this file.

/alpha/upload

PREVIEW - may change or disappear without notice
Description

Create a new file with the contents provided in the request. Note that this endpoint is part of the properties API alpha and is slightly different from upload.
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/alpha/upload
Authentication
User Authentication
Endpoint format
Content-upload
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/alpha/upload \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"path\": \"/Homework/math/Matrices.txt\",\"mode\": \"add\",\"autorename\": true,\"mute\": false,\"property_groups\": [{\"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\",\"fields\": [{\"name\": \"Security Policy\",\"value\": \"Confidential\"}]}]}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "path": "/Homework/math/Matrices.txt",
    "mode": "add",
    "autorename": true,
    "mute": false,
    "property_groups": [
        {
            "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",
            "fields": [
                {
                    "name": "Security Policy",
                    "value": "Confidential"
                }
            ]
        }
    ]
}
CommitInfoWithProperties
path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)") 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 contain anything, the file is always written; no conflict. (b) If the target path contains a folder, it's always a conflict. (c) If the target path contains 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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"
    }
}
UploadErrorWithProperties (union)
The value will be one of the following datatypes:
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 modify or delete team folders.
upload_session_id String The upload session ID; this may be used to retry the commit.
properties_error InvalidPropertyGroupError
InvalidPropertyGroupError (union)
The value will be one of the following datatypes:
template_not_found String(min_length=1, pattern="(/|ptid:).*") Property template does not exist for given identifier.
restricted_content Void You do not have the permissions to modify this property 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? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
property_field_too_large Void A field value in this property group is too large.
does_not_fit_template Void The property group specified does not conform to the property template.

/copy

Description

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

URL Structure
https://api.dropboxapi.com/2/files/copy
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/copy \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"from_path\": \"/Homework/math\",\"to_path\": \"/Homework/algebra\",\"allow_shared_folder\": false,\"autorename\": false}"
Parameters
{
    "from_path": "/Homework/math",
    "to_path": "/Homework/algebra",
    "allow_shared_folder": false,
    "autorename": false
}
RelocationArg
from_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)") Path in the user's Dropbox to be copied or moved.
to_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)") 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.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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: 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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 modify 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 modify 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.

/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}"
Parameters
{
    "entries": [
        {
            "from_path": "/Homework/math",
            "to_path": "/Homework/algebra"
        }
    ],
    "allow_shared_folder": false,
    "autorename": 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]+(/.*)?)") Path in the user's Dropbox to be copied or moved.
to_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)") 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.
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 (RelocationResult)
RelocationResult
metadata Metadata
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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 (RelocationResult)
RelocationResult
metadata Metadata
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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 modify 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 modify 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.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.

/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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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 modify 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.

/create_folder

Description

Create a folder at a given path.

URL Structure
https://api.dropboxapi.com/2/files/create_folder
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/create_folder \
    --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
{
    "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"
                }
            ]
        }
    ]
}
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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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 modify or delete team folders.

/delete

Description

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

URL Structure
https://api.dropboxapi.com/2/files/delete
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/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]+(/.*)?)") Path in the user's Dropbox to delete.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
Errors
{
    "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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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 modify 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]+(/.*)?)") 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 DeleteResult
DeleteResult
metadata Metadata
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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 modify or delete team folders.
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 DeleteResult
DeleteResult
metadata Metadata
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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 modify or delete team folders.
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_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.

/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.
rev String(min_length=9, pattern="[0-9a-f]+")? 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.

/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
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.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.

/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.
rev String(min_length=9, pattern="[0-9a-f]+")? 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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.

/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
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}"
Parameters
{
    "path": "/Homework/math",
    "recursive": false,
    "include_media_info": false,
    "include_deleted": false,
    "include_has_explicit_shared_members": false
}
ListFolderArg
path String(pattern="(/(.|[\r\n])*)?|(ns:[0-9]+(/.*)?)") The path to the folder you want to see the contents of.
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.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.

/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
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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
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}"
Parameters
{
    "path": "/Homework/math",
    "recursive": false,
    "include_media_info": false,
    "include_deleted": false,
    "include_has_explicit_shared_members": false
}
ListFolderArg
path String(pattern="(/(.|[\r\n])*)?|(ns:[0-9]+(/.*)?)") The path to the folder you want to see the contents of.
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.
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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.

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

Return revisions of a file.

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\",\"limit\": 10}"
Parameters
{
    "path": "/root/word.docx",
    "limit": 10
}
ListRevisionsArg
path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") The path to the file you want to see the revisions of.
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 is deleted.
entries List of (FileMetadata) The revisions for the file. Only non-delete revisions 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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"
    }
}
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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.

/move

Description

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

URL Structure
https://api.dropboxapi.com/2/files/move
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/move \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"from_path\": \"/Homework/math\",\"to_path\": \"/Homework/algebra\",\"allow_shared_folder\": false,\"autorename\": false}"
Parameters
{
    "from_path": "/Homework/math",
    "to_path": "/Homework/algebra",
    "allow_shared_folder": false,
    "autorename": false
}
RelocationArg
from_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)") Path in the user's Dropbox to be copied or moved.
to_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)") 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.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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: 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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 modify 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 modify 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.

/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}"
Parameters
{
    "entries": [
        {
            "from_path": "/Homework/math",
            "to_path": "/Homework/algebra"
        }
    ],
    "allow_shared_folder": false,
    "autorename": 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]+(/.*)?)") Path in the user's Dropbox to be copied or moved.
to_path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)") 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.
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 (RelocationResult)
RelocationResult
metadata Metadata
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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 (RelocationResult)
RelocationResult
metadata Metadata
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? Deprecated. Please use FileSharingInfo.parent_shared_folder_id or FolderSharingInfo.parent_shared_folder_id instead. This field is optional.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? 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. This field is optional.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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 modify 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 modify 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.
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.

/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]+(/.*)?)") Path in the user's Dropbox to delete.
Returns

No return values.

Errors
{
    "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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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 modify or delete team folders.

/properties/add

PREVIEW - may change or disappear without notice
Description

Add custom properties to a file using a filled property template. See properties/template/add to create new property templates.

URL Structure
https://api.dropboxapi.com/2/files/properties/add
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/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"
                }
            ]
        }
    ]
}
PropertyGroupWithPath
path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file.
property_groups List of (PropertyGroup) Filled custom property templates associated with a file.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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: 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:).*") Property template does not exist for given identifier.
restricted_content Void You do not have the permissions to modify this property 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? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
property_field_too_large Void A field value in this property group is too large.
does_not_fit_template Void The property group specified does not conform to the property template.
property_group_already_exists Void This property group already exists for this file.

/properties/overwrite

PREVIEW - may change or disappear without notice
Description

Overwrite custom properties from a specified template associated with a file.

URL Structure
https://api.dropboxapi.com/2/files/properties/overwrite
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/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"
                }
            ]
        }
    ]
}
PropertyGroupWithPath
path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file.
property_groups List of (PropertyGroup) Filled custom property templates associated with a file.
PropertyGroup
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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: 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:).*") Property template does not exist for given identifier.
restricted_content Void You do not have the permissions to modify this property 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? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
property_field_too_large Void A field value in this property group is too large.
does_not_fit_template Void The property group specified does not conform to the property template.

/properties/remove

PREVIEW - may change or disappear without notice
Description

Remove all custom properties from a specified template associated with a file. To remove specific property key value pairs, see properties/update. To update a property template, see properties/template/update. Property templates can't be removed once created.

URL Structure
https://api.dropboxapi.com/2/files/properties/remove
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/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.
property_template_ids List of (String(min_length=1, pattern="(/|ptid:).*")) A list of identifiers for a property template created by route properties/template/add.
Returns

No return values.

Errors
Example: restricted_content
{
    "error_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
RemovePropertiesError (union)
The value will be one of the following datatypes:
template_not_found String(min_length=1, pattern="(/|ptid:).*") Property template does not exist for given identifier.
restricted_content Void You do not have the permissions to modify this property 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? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
property_group_lookup LookUpPropertiesError
LookUpPropertiesError (union)
The value will be one of the following datatypes:
property_group_not_found Void This property group does not exist for this file.

/properties/template/get

PREVIEW - may change or disappear without notice
Description

Get the schema for a specified template.

URL Structure
https://api.dropboxapi.com/2/files/properties/template/get
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/properties/template/get \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"}"
Parameters
{
    "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
}
GetPropertyTemplateArg
This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") An identifier for property template added by route properties/template/add.
Returns
{
    "name": "Security",
    "description": "These properties describe how confidential this file 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"
            }
        }
    ]
}
GetPropertyTemplateResult
The Property template for the specified template. This datatype comes from an imported namespace originally defined in the properties namespace.
name String A display name for the property template. Property template names can be up to 256 bytes.
description String Description for new property template. Property template descriptions can be up to 1024 bytes.
fields List of (PropertyFieldTemplate) This is a list of custom properties associated with a property template. There can be up to 64 properties in a single property template.
PropertyFieldTemplate
Describe a single property field type which that can be part of a property template. This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
description String This is the description for a custom property in a property template. File property description can be up to 1024 bytes.
type PropertyType This is the data type of the value of this property. This type will be enforced upon property creation and modifications.
PropertyType (open union)
Data type of the given property added. This endpoint is in beta and only properties of type strings is supported. This datatype comes from an imported namespace originally defined in the properties namespace. The value will be one of the following datatypes. New values may be introduced as our API evolves.
string Void The associated property 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"
    }
}
PropertyTemplateError (open union)
This datatype comes from an imported namespace originally defined in the properties namespace. 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:).*") Property template does not exist for given identifier.
restricted_content Void You do not have the permissions to modify this property template.

/properties/template/list

PREVIEW - may change or disappear without notice
Description

Get the property template identifiers for a user. To get the schema of each template use properties/template/get.

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

No parameters.

Returns
{
    "template_ids": [
        "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
    ]
}
ListPropertyTemplateIds
This datatype comes from an imported namespace originally defined in the properties namespace.
template_ids List of (String(min_length=1, pattern="(/|ptid:).*")) List of identifiers for templates added by route properties/template/add.
Errors
Example: restricted_content
{
    "error_summary": "restricted_content/...",
    "error": {
        ".tag": "restricted_content"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
PropertyTemplateError (open union)
This datatype comes from an imported namespace originally defined in the properties namespace. 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:).*") Property template does not exist for given identifier.
restricted_content Void You do not have the permissions to modify this property template.

/properties/update

PREVIEW - may change or disappear without notice
Description

Add, update or remove custom properties from a specified template associated with a file. Fields that already exist and not described in the request will not be modified.

URL Structure
https://api.dropboxapi.com/2/files/properties/update
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/files/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": []
        }
    ]
}
UpdatePropertyGroupArg
path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file.
update_property_groups List of (PropertyGroupUpdate) Filled custom property templates associated with a file.
PropertyGroupUpdate
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template.
add_or_update_fields List of (PropertyField)? List of property fields to update if the field already exists. If the field doesn't exist, add the field to the property group. This field is optional.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. Values can be up to 1024 bytes.
remove_fields List of (String)? List of property field names to remove from property group if the field exists. 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: 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:).*") Property template does not exist for given identifier.
restricted_content Void You do not have the permissions to modify this property 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? 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
property_field_too_large Void A field value in this property group is too large.
does_not_fit_template Void The property group specified does not conform to the property template.
property_group_lookup LookUpPropertiesError
LookUpPropertiesError (union)
The value will be one of the following datatypes:
property_group_not_found Void This property group does not exist for this file.

/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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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.
invalid_path_root PathRootError The path root parameter provided is invalid.
PathRootError
path_root String? The user's latest path root value. None if the user no longer has a path root. This field is optional.
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 modify 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
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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 modify 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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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 modify 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
}
CommitInfo
path String(pattern="(/(.|[\r\n])*)|(ns:[0-9]+(/.*)?)") 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 contain anything, the file is always written; no conflict. (b) If the target path contains a folder, it's always a conflict. (c) If the target path contains 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.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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 modify or delete team folders.
upload_session_id String The upload session ID; this may be used to retry the commit.

/upload_session/append

DEPRECATED BY /upload_session/append_v2
Description

Append more data to an upload session.
A single request should not upload more than 150 MB.

URL Structure
https://content.dropboxapi.com/2/files/upload_session/append
Authentication
User Authentication
Endpoint format
Content-upload
Example
Get access token for:
curl -X POST https://content.dropboxapi.com/2/files/upload_session/append \
    --header "Authorization: Bearer " \
    --header "Dropbox-API-Arg: {\"session_id\": \"1234faaf0678bcde\",\"offset\": 0}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @local_file.txt
Parameters
{
    "session_id": "1234faaf0678bcde",
    "offset": 0
}
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.
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/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
    }
}
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]+(/.*)?)") 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 contain anything, the file is always written; no conflict. (b) If the target path contains a folder, it's always a conflict. (c) If the target path contains 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.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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: 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 modify 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.

/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\": {\".tag\": \"add\"},\"autorename\": true,\"mute\": false}}]}"
Parameters
{
    "entries": [
        {
            "cursor": {
                "session_id": "1234faaf0678bcde",
                "offset": 0
            },
            "commit": {
                "path": "/Homework/math/Matrices.txt",
                "mode": {
                    ".tag": "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]+(/.*)?)") 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 contain anything, the file is always written; no conflict. (b) If the target path contains a folder, it's always a conflict. (c) If the target path contains 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.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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 modify 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.
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_id String(pattern="[-_0-9a-zA-Z:]+")? 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
Collection of custom properties in filled property templates. This datatype comes from an imported namespace originally defined in the properties namespace.
template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for a property template type.
fields List of (PropertyField) This is a list of custom properties associated with a file. There can be up to 32 properties for a template.
PropertyField
This datatype comes from an imported namespace originally defined in the properties namespace.
name String This is the name or key of a custom property in a property template. File property names can be up to 256 bytes.
value String Value of a custom property attached to a file. 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 modify 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.
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/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/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\": {\".tag\": \"view_and_comment\"}}],\"custom_message\": \"Welcome to Paper.\",\"quiet\": false}"
Parameters
{
    "doc_id": "uaSvRuxvnkFa12PTkBv5q",
    "members": [
        {
            "member": {
                ".tag": "email",
                "email": "justin@example.com"
            },
            "permission_level": {
                ".tag": "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_comment Boolean 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.
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\": {\".tag\": \"editor\"}},{\"member\": {\".tag\": \"dropbox_id\",\"dropbox_id\": \"dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q\"},\"access_level\": {\".tag\": \"viewer\"}}],\"quiet\": false,\"custom_message\": \"Documentation for launch day\"}"
Parameters
{
    "shared_folder_id": "84528192421",
    "members": [
        {
            "member": {
                ".tag": "email",
                "email": "justin@example.com"
            },
            "access_level": {
                ".tag": "editor"
            }
        },
        {
            "member": {
                ".tag": "dropbox_id",
                "dropbox_id": "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"
            },
            "access_level": {
                ".tag": "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 The access level to grant member to the shared folder. AccessLevel.owner is disallowed. 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.
quiet Boolean Whether added members should be notified via email and device notifications of their invite. The default for this field is False.
custom_message String(min_length=1)? Optional message to display to added members in their invitation. This field is optional.
Returns

No return values.

Errors
{
    "error_summary": "no_permission/...",
    "error": {
        ".tag": "no_permission"
    }
}
Example: member
{
    "error_summary": "bad_member/invalid_dropbox_id/...",
    "error": {
        ".tag": "bad_member",
        "bad_member": {
            ".tag": "invalid_dropbox_id",
            "invalid_dropbox_id": "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"
        }
    }
}
Example: email_unverified
{
    "error_summary": "email_unverified/...",
    "error": {
        ".tag": "email_unverified"
    }
}
Example: cant_share_outside_team
{
    "error_summary": "cant_share_outside_team/...",
    "error": {
        ".tag": "cant_share_outside_team"
    }
}
Example: rate_limit
{
    "error_summary": "rate_limit/...",
    "error": {
        ".tag": "rate_limit"
    }
}
Example: too_many_invitees
{
    "error_summary": "too_many_invitees/...",
    "error": {
        ".tag": "too_many_invitees"
    }
}
Example: insufficient_plan
{
    "error_summary": "insufficient_plan/...",
    "error": {
        ".tag": "insufficient_plan"
    }
}
Example: team_folder
{
    "error_summary": "team_folder/...",
    "error": {
        ".tag": "team_folder"
    }
}
Example: no_permission
{
    "error_summary": "no_permission/...",
    "error": {
        ".tag": "no_permission"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
AddFolderMemberError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
access_error SharedFolderAccessError Unable to access shared folder.
SharedFolderAccessError (open union)
There is an error accessing the shared folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_id Void This shared folder ID is invalid.
not_a_member Void The user is not a member of the shared folder thus cannot access it.
email_unverified Void The current user's e-mail address is unverified.
unmounted Void The shared folder is unmounted.
email_unverified Void The current user's e-mail address is unverified.
bad_member AddMemberSelectorError AddFolderMemberArg.members contains a bad invitation recipient.
AddMemberSelectorError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
automatic_group Void Automatically created groups can only be added to team folders.
invalid_dropbox_id String(min_length=1) The value is the ID that could not be identified.
invalid_email String(max_length=255, pattern="^['&A-Za-z0-9._%+-]+@[A-Za-z0-9-][A-Za-z0-9.-]*.[A-Za-z]{2,15}$") The value is the e-email address that is malformed.
unverified_dropbox_id String(min_length=1) The value is the ID of the Dropbox user with an unverified e-mail address. Invite unverified users by e-mail address instead of by their Dropbox ID.
group_deleted Void At least one of the specified groups in AddFolderMemberArg.members is deleted.
group_not_on_team Void Sharing to a group that is not on the current user's team.
cant_share_outside_team Void Your team policy does not allow sharing outside of the team.
too_many_members UInt64 The value is the member limit that was reached.
too_many_pending_invites UInt64 The value is the pending invite limit that was reached.
rate_limit Void The current user has hit the limit of invites they can send per day. Try again in 24 hours.
too_many_invitees Void The current user is trying to share with too many people at once.
insufficient_plan Void The current user's account doesn't support this action. An example of this is when adding a read-only member. This action can only be performed by users that have upgraded to a Pro or Business plan.
team_folder Void This action cannot be performed on a team shared folder.
no_permission Void The current user does not have permission to perform this action.

/change_file_member_access

DEPRECATED BY /update_file_member
Description

Identical to update_file_member but with less information returned.

URL Structure
https://api.dropboxapi.com/2/sharing/change_file_member_access
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/change_file_member_access \
    --header "Authorization: Bearer " \
    --header "Content-Type: application/json" \
    --data "{\"file\": \"id:3kmLmQFnf1AAAAAAAAAAAw\",\"member\": {\".tag\": \"email\",\"email\": \"justin@example.com\"},\"access_level\": \"viewer\"}"
Parameters
{
    "file": "id:3kmLmQFnf1AAAAAAAAAAAw",
    "member": {
        ".tag": "email",
        "email": "justin@example.com"
    },
    "access_level": "viewer"
}
ChangeFileMemberAccessArgs
Arguments for change_file_member_access.
file String(min_length=1, pattern="((/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?") File for which we are changing a member's access.
member MemberSelector The member whose access we are changing.
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 The new access level for the member.
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.
Returns
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.
path String The full path to the parent shared folder relative to the acting user's root.
Errors
Example: invalid_member
{
    "error_summary": "invalid_member/...",
    "error": {
        ".tag": "invalid_member"
    }
}
Example: no_permission
{
    "error_summary": "no_permission/...",
    "error": {
        ".tag": "no_permission"
    }
}
Example: other
{
    "error_summary": "other/...",
    "error": {
        ".tag": "other"
    }
}
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.
path String The full path to the parent shared folder relative to the acting user's root.

/check_job_status

Description

Returns the status of an asynchronous job.
Apps must have full Dropbox access to use this endpoint.

URL Structure
https://api.dropboxapi.com/2/sharing/check_job_status
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/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
Example: in_progress
{
    ".tag": "in_progress"
}
Example: complete
{
    ".tag": "complete"
}
JobStatus (union)
The value will be one of the following datatypes:
in_progress Void The asynchronous job is still in progress.
complete Void The asynchronous job has finished.
failed JobError The asynchronous job returned an error.
JobError (open union)
Error occurred while performing an asynchronous job from unshare_folder or remove_folder_member. The value will be one of the following datatypes. New values may be introduced as our API evolves.
unshare_folder_error UnshareFolderError Error occurred while performing unshare_folder action.
UnshareFolderError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
access_error SharedFolderAccessError
SharedFolderAccessError (open union)
There is an error accessing the shared folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_id Void This shared folder ID is invalid.
not_a_member Void The user is not a member of the shared folder thus cannot access it.
email_unverified Void The current user's e-mail address is unverified.
unmounted Void The shared folder is unmounted.
team_folder Void This action cannot be performed on a team shared folder.
no_permission Void The current user does not have permission to perform this action.
too_many_files Void This shared folder has too many files to be unshared.
remove_folder_member_error RemoveFolderMemberError Error occurred while performing remove_folder_member action.
RemoveFolderMemberError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
access_error SharedFolderAccessError
SharedFolderAccessError (open union)
There is an error accessing the shared folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_id Void This shared folder ID is invalid.
not_a_member Void The user is not a member of the shared folder thus cannot access it.
email_unverified Void The current user's e-mail address is unverified.
unmounted Void The shared folder is unmounted.
member_error SharedFolderMemberError
SharedFolderMemberError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_dropbox_id Void The target dropbox_id is invalid.
not_a_member Void The target dropbox_id is not a member of the shared folder.
no_explicit_access MemberAccessLevelResult The target member only has inherited access to the shared 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.
path String The full path to the parent shared folder relative to the acting user's root.
folder_owner Void The target user is the owner of the shared folder. You can't remove this user until ownership has been transferred to another member.
group_access Void The target user has access to the shared folder via a group.
team_folder Void This action cannot be performed on a team shared folder.
no_permission Void The current user does not have permission to perform this action.
relinquish_folder_membership_error RelinquishFolderMembershipError Error occurred while performing relinquish_folder_membership action.
RelinquishFolderMembershipError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
access_error SharedFolderAccessError
SharedFolderAccessError (open union)
There is an error accessing the shared folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_id Void This shared folder ID is invalid.
not_a_member Void The user is not a member of the shared folder thus cannot access it.
email_unverified Void The current user's e-mail address is unverified.
unmounted Void The shared folder is unmounted.
folder_owner Void The current user is the owner of the shared folder. Owners cannot relinquish membership to their own folders. Try unsharing or transferring ownership first.
mounted Void The shared folder is currently mounted. Unmount the shared folder before relinquishing membership.
group_access Void The current user has access to the shared folder via a group. You can't relinquish membership to folders shared via groups.
team_folder Void This action cannot be performed on a team shared folder.
no_permission Void The current user does not have permission to perform this action.
no_explicit_access Void The current user only has inherited access to the shared folder. You can't relinquish inherited membership to folders.
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.

/check_remove_member_job_status

Description

Returns the status of an asynchronous job for sharing a folder.
Apps must have full Dropbox access to use this endpoint.

URL Structure
https://api.dropboxapi.com/2/sharing/check_remove_member_job_status
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/check_remove_member_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": "complete"
}
Example: in_progress
{
    ".tag": "in_progress"
}
RemoveMemberJobStatus (union)
The value will be one of the following datatypes:
in_progress Void The asynchronous job is still in progress.
complete MemberAccessLevelResult Removing the folder member has finished. The value is information about whether the member has another form of access.
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.
path String The full path to the parent shared folder relative to the acting user's root.
failed RemoveFolderMemberError
RemoveFolderMemberError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
access_error SharedFolderAccessError
SharedFolderAccessError (open union)
There is an error accessing the shared folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_id Void This shared folder ID is invalid.
not_a_member Void The user is not a member of the shared folder thus cannot access it.
email_unverified Void The current user's e-mail address is unverified.
unmounted Void The shared folder is unmounted.
member_error SharedFolderMemberError
SharedFolderMemberError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
invalid_dropbox_id Void The target dropbox_id is invalid.
not_a_member Void The target dropbox_id is not a member of the shared folder.
no_explicit_access MemberAccessLevelResult The target member only has inherited access to the shared 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.
path String The full path to the parent shared folder relative to the acting user's root.
folder_owner Void The target user is the owner of the shared folder. You can't remove this user until ownership has been transferred to another member.
group_access Void The target user has access to the shared folder via a group.
team_folder Void This action cannot be performed on a team shared folder.
no_permission Void The current user does not have permission to perform this action.
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.

/check_share_job_status

Description

Returns the status of an asynchronous job for sharing a folder.
Apps must have full Dropbox access to use this endpoint.

URL Structure
https://api.dropboxapi.com/2/sharing/check_share_job_status
Authentication
User Authentication
Endpoint format
RPC
Example
Get access token for:
curl -X POST https://api.dropboxapi.com/2/sharing/check_share_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": "complete",
    "access_type": {
        ".tag": "owner"
    },
    "is_inside_team_folder": false,
    "is_team_folder": false,
    "name": "dir",
    "policy": {
        "acl_update_policy": {
            ".tag": "owner"
        },
        "shared_link_policy": {
            ".tag": "anyone"
        },
        "member_policy": {
            ".tag": "anyone"
        },
        "resolved_member_policy": {
            ".tag": "team"
        }
    },
    "preview_url": "https://www.dropbox.com/scl/fo/fir9vjelf",
    "shared_folder_id": "84528192421",
    "time_invited": "2016-01-20T00:00:00Z",
    "path_lower": "/dir",
    "link_metadata": {
        "audience_options": [
            {
                ".tag": "public"
            },
            {
                ".tag": "team"
            },
            {
                ".tag": "members"
            }
        ],
        "current_audience": {
            ".tag": "public"
        },
        "link_permissions": [
            {
                "action": {
                    ".tag": "change_audience"
                },
                "allow": true
            }
        ],
        "password_protected": false,
        "url": ""
    },
    "permissions": []
}
Example: in_progress
{
    ".tag": "in_progress"
}
ShareFolderJobStatus (union)
The value will be one of the following datatypes:
in_progress Void The asynchronous job is still in progress.
complete SharedFolderMetadata The share job has finished. The value is the metadata for the folder.
SharedFolderMetadata
The metadata which includes basic information about the shared folder.
access_type AccessLevel The current user's access level for this shared folder.
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.
is_inside_team_folder Boolean Whether this folder is inside of a team folder.
is_team_folder Boolean Whether this folder is a team folder.
name String The name of the this shared folder.
policy FolderPolicy Policies governing this shared folder.
FolderPolicy
A set of policies governing membership and privileges for a shared folder.
acl_update_policy AclUpdatePolicy Who can add and remove members from this shared folder.
AclUpdatePolicy (open union)
Who can change a shared folder's access control list (ACL). In other words, who can add, remove, or change the privileges of members. The value will be one of the following datatypes. New values may be introduced as our API evolves.
owner Void Only the owner can update the ACL.
editors Void Any editor can update the ACL. This may be further restricted to editors on the same team.
shared_link_policy SharedLinkPolicy Who links can be shared with.
SharedLinkPolicy (open union)
Who can view shared links in this folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
anyone Void Links can be shared with anyone.
team Void Links can be shared with anyone on the same team as the owner.
members Void Links can only be shared among members of the shared folder.
member_policy MemberPolicy? Who can be a member of this shared folder, as set on the folder itself. The effective policy may differ from this value if the team-wide policy is more restrictive. Present only if the folder is owned by a team. This field is optional.
MemberPolicy (open union)
Policy governing who can be a member of a shared folder. Only applicable to folders owned by a user on a team. The value will be one of the following datatypes. New values may be introduced as our API evolves.
team Void Only a teammate can become a member.
anyone Void Anyone can become a member.
resolved_member_policy MemberPolicy? Who can be a member of this shared folder, taking into account both the folder and the team-wide policy. This value may differ from that of member_policy if the team-wide policy is more restrictive than the folder policy. Present only if the folder is owned by a team. This field is optional.
MemberPolicy (open union)
Policy governing who can be a member of a shared folder. Only applicable to folders owned by a user on a team. The value will be one of the following datatypes. New values may be introduced as our API evolves.
team Void Only a teammate can become a member.
anyone Void Anyone can become a member.
viewer_info_policy ViewerInfoPolicy? Who can enable/disable viewer info for this shared folder. This field is optional.
ViewerInfoPolicy (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
enabled Void Viewer information is available on this file.
disabled Void Viewer information is disabled on this file.
preview_url String URL for displaying a web preview of the shared folder.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") The ID of the shared folder.
time_invited Timestamp(format="%Y-%m-%dT%H:%M:%SZ") Timestamp indicating when the current user was invited to this shared folder.
owner_team Team? The team that owns the folder. This field is not present if the folder is not owned by a team. This field is optional.
Team
Information about a team. This datatype comes from an imported namespace originally defined in the users namespace.
id String The team's unique ID.
name String The name of the team.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? The ID of the parent shared folder. This field is present only if the folder is contained within another shared folder. This field is optional.
path_lower String? The lower-cased full path of this shared folder. Absent for unmounted folders. This field is optional.
link_metadata SharedContentLinkMetadata? The metadata of the shared content link to this shared folder. Absent if there is no link on the folder. This is for an unreleased feature so it may not be returned yet. This field is optional.
SharedContentLinkMetadata
Metadata of a shared link for a file or folder.
audience_options List of (LinkAudience) The audience options that are available for the content. Some audience options may be unavailable. For example, team_only may be unavailable if the content is not owned by a user on a team. The 'default' audience option is always available if the user can modify link settings.
LinkAudience (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
public Void Link is accessible by anyone.
team Void Link is accessible only by team members.
members Void Link is accessible only by members of the content.
current_audience LinkAudience The current audience of the link.
LinkAudience (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
public Void Link is accessible by anyone.
team Void Link is accessible only by team members.
members Void Link is accessible only by members of the content.
link_permissions List of (LinkPermission) A list of permissions for actions you can perform on the link.
LinkPermission
Permissions for actions that can be performed on a link.
action LinkAction
LinkAction (open union)
Actions that can be performed on a link. The value will be one of the following datatypes. New values may be introduced as our API evolves.
change_access_level Void Change the access level of the link.
change_audience Void Change the audience of the link.
remove_expiry Void Remove the expiry date of the link.
remove_password Void Remove the password of the link.
set_expiry Void Create or modify the expiry date of the link.
set_password Void Create or modify the password of the link.
allow Boolean
reason PermissionDeniedReason? 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.
password_protected Boolean Whether the link is protected by a password.
url String The URL of the link.
access_level AccessLevel? The access level on the link for this file. 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.
audience_restricting_shared_folder AudienceRestrictingSharedFolder? The shared folder that prevents the link audience for this link from being more restrictive. This field is optional.
AudienceRestrictingSharedFolder
Information about the shared folder that prevents the link audience for this link from being more restrictive.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") The ID of the shared folder.
name String The name of the shared folder.
audience LinkAudience The link audience of the shared folder.
LinkAudience (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
public Void Link is accessible by anyone.
team Void Link is accessible only by team members.
members Void Link is accessible only by members of the content.
expiry Timestamp(format="%Y-%m-%dT%H:%M:%SZ")? Whether the link has an expiry set on it. A link with an expiry will have its audience changed to members when the expiry is reached. This field is optional.
permissions List of (FolderPermission)? Actions the current user may perform on the folder and its contents. The set of permissions corresponds to the FolderActions in the request. This field is optional.
FolderPermission
Whether the user is allowed to take the action on the shared folder.
action FolderAction The action that the user may wish to take on the folder.
FolderAction (open union)
Actions that may be taken on shared folders. The value will be one of the following datatypes. New values may be introduced as our API evolves.
change_options Void Change folder options, such as who can be invited to join the folder.
disable_viewer_info Void Disable viewer information for this folder.
edit_contents Void Change or edit contents of the folder.
enable_viewer_info Void Enable viewer information on the folder.
invite_editor Void Invite a user or group to join the folder with read and write permission.
invite_viewer Void Invite a user or group to join the folder with read permission.
invite_viewer_no_comment Void Invite a user or group to join the folder with read permission but no comment permissions.
relinquish_membership Void Relinquish one's own membership in the folder.
unmount Void Unmount the folder.
unshare Void Stop sharing this folder.
leave_a_copy Void Keep a copy of the contents upon leaving or being kicked from the folder.
share_link Void This action is deprecated. Use create_link instead.
create_link Void Create a shared link for 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, or if no reason is available. 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.
failed ShareFolderError
ShareFolderError (union)
The value will be one of the following datatypes:
email_unverified Void The current user's e-mail address is unverified.
bad_path SharePathError ShareFolderArg.path is invalid.
SharePathError (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
is_file Void A file is at the specified path.
inside_shared_folder Void We do not support sharing a folder inside a shared folder.
contains_shared_folder Void We do not support shared folders that contain shared folders.
contains_app_folder Void We do not support shared folders that contain app folders.
contains_team_folder Void We do not support shared folders that contain team folders.
is_app_folder Void We do not support sharing an app folder.
inside_app_folder Void We do not support sharing a folder inside an app folder.
is_public_folder Void A public folder can't be shared this way. Use a public link instead.
inside_public_folder Void A folder inside a public folder can't be shared this way. Use a public link instead.
already_shared SharedFolderMetadata Folder is already shared. Contains metadata about the existing shared folder.
SharedFolderMetadata
The metadata which includes basic information about the shared folder.
access_type AccessLevel The current user's access level for this shared folder.
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.
is_inside_team_folder Boolean Whether this folder is inside of a team folder.
is_team_folder Boolean Whether this folder is a team folder.
name String The name of the this shared folder.
policy FolderPolicy Policies governing this shared folder.
FolderPolicy
A set of policies governing membership and privileges for a shared folder.
acl_update_policy AclUpdatePolicy Who can add and remove members from this shared folder.
AclUpdatePolicy (open union)
Who can change a shared folder's access control list (ACL). In other words, who can add, remove, or change the privileges of members. The value will be one of the following datatypes. New values may be introduced as our API evolves.
owner Void Only the owner can update the ACL.
editors Void Any editor can update the ACL. This may be further restricted to editors on the same team.
shared_link_policy SharedLinkPolicy Who links can be shared with.
SharedLinkPolicy (open union)
Who can view shared links in this folder. The value will be one of the following datatypes. New values may be introduced as our API evolves.
anyone Void Links can be shared with anyone.
team Void Links can be shared with anyone on the same team as the owner.
members Void Links can only be shared among members of the shared folder.
member_policy MemberPolicy? Who can be a member of this shared folder, as set on the folder itself. The effective policy may differ from this value if the team-wide policy is more restrictive. Present only if the folder is owned by a team. This field is optional.
MemberPolicy (open union)
Policy governing who can be a member of a shared folder. Only applicable to folders owned by a user on a team. The value will be one of the following datatypes. New values may be introduced as our API evolves.
team Void Only a teammate can become a member.
anyone Void Anyone can become a member.
resolved_member_policy MemberPolicy? Who can be a member of this shared folder, taking into account both the folder and the team-wide policy. This value may differ from that of member_policy if the team-wide policy is more restrictive than the folder policy. Present only if the folder is owned by a team. This field is optional.
MemberPolicy (open union)
Policy governing who can be a member of a shared folder. Only applicable to folders owned by a user on a team. The value will be one of the following datatypes. New values may be introduced as our API evolves.
team Void Only a teammate can become a member.
anyone Void Anyone can become a member.
viewer_info_policy ViewerInfoPolicy? Who can enable/disable viewer info for this shared folder. This field is optional.
ViewerInfoPolicy (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
enabled Void Viewer information is available on this file.
disabled Void Viewer information is disabled on this file.
preview_url String URL for displaying a web preview of the shared folder.
shared_folder_id String(pattern="[-_0-9a-zA-Z:]+") The ID of the shared folder.
time_invited Timestamp(format="%Y-%m-%dT%H:%M:%SZ") Timestamp indicating when the current user was invited to this shared folder.
owner_team Team? The team that owns the folder. This field is not present if the folder is not owned by a team. This field is optional.
Team
Information about a team. This datatype comes from an imported namespace originally defined in the users namespace.
id String The team's unique ID.
name String The name of the team.
parent_shared_folder_id String(pattern="[-_0-9a-zA-Z:]+")? The ID of the parent shared folder. This field is present only if the folder is contained within another shared folder. This field is optional.
path_lower String? The lower-cased full path of this shared folder. Absent for unmounted folders. This field is optional.
link_metadata SharedContentLinkMetadata? The metadata of the shared content link to this shared folder. Absent if there is no link on the folder. This is for an unreleased feature so it may not be returned yet. This field is optional.
SharedContentLinkMetadata
Metadata of a shared link for a file or folder.
audience_options List of (LinkAudience) The audience options that are available for the content. Some audience options may be unavailable. For example, team_only may be unavailable if the content is not owned by a user on a team. The 'default' audience option is always available if the user can modify link settings.
LinkAudience (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
public Void Link is accessible by anyone.
team Void Link is accessible only by team members.
members Void Link is accessible only by members of the content.
current_audience LinkAudience The current audience of the link.
LinkAudience (open union)
The value will be one of the following datatypes. New values may be introduced as our API evolves.
public Void Link is accessible by anyone.
team Void Link is accessible only by team members.
members Void Link is accessible only by members of the content.
link_permissions List of (LinkPermission) A list of permissions for actions you can perform on the link.