R Rdrop 2 Download Several File

04 Dec, 2021 Post a Comment

Dropbox for HTTP Developers

Dropbox API v2

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

Request and response formats

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

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

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

RPC endpoints

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

Content-upload endpoints

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

Content-download endpoints

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

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

For information on how to properly encode the JSON, see the JSON encoding page.

Browser-based JavaScript and CORS pre-flight requests

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

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

Date format

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

2015-05-15T15:50:38Z

Path formats

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

Every file and folder in Dropbox also has an ID (e.g. "id:abc123xyz") that can be obtained from any endpoint that returns metadata. These IDs are case-sensitive, so they should always be stored with their case preserved, and always compared in a case-sensitive manner. Some endpoints, as noted in the individual endpoint documentation below, can accept IDs in addition to normal paths. A path relative to a folder's ID can be constructed by using a slash (e.g. "id:abc123xyz/hello.txt").

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

Path case insensitivity

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

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

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

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 three 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 PKCE flow is an extension of the code flow that uses dynamically generated codes instead of a secret to perform an OAuth exchange from public clients. The PKCE flow is a newer, more secure alternative to the token (implicit) flow. It is the recommended flow for client-side apps, such as mobile or JavaScript apps.
[Legacy. We recommend the PKCE flow.] -- The token or implicit grant flow returns the bearer token via the redirect_uri callback, rather than requiring your app to make a second call to a server. This is useful for pure client-side apps, such as mobile apps or JavaScript-based apps.

For more information on the code and token flows, see Section 1.3 of the OAuth 2 spec. For more info on the PKCE extension, see RFC 7636

Your app should send the user to this app authorization page in their system browser, which will display the permissions being granted. If the user isn't already signed in to the Dropbox website, they will be prompted to do so on this web page. This web page should not be displayed in a web-view. This is in order to maintain compatibility with the website and to comply with Google's policy against processing their OAuth flow inside a web-view, to support users who sign in to Dropbox using their Google accounts. Learn about the dropbox.com system requirements.

URL Structure

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

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

Method

GET

Example

Example: Auth URL for code flow

https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code

Example: Auth URL for code flow with offline token access type

https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&token_access_type=offline&response_type=code

Example: Auth URL for PKCE code flow

https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code&code_challenge=<CHALLENGE>&code_challenge_method=<METHOD>

Parameters

response_type String The grant type requested, either token or code.

client_id String The app's key, found in the App Console.

redirect_uri String? Where to redirect the user after authorization has completed. This must be the exact URI registered in the App Console; even 'localhost' must be listed if it is used for testing. All redirect URIs must be HTTPS except for localhost URIs. A redirect URI is required for the token flow, but optional for the code flow. If the redirect URI is omitted, the code will be presented directly to the user and they will be invited to enter the information in your app.

scope String? This parameter allows your user to authorize a subset of the scopes selected in the App Console. Multiple scopes are separated by a space. If this parameter is omitted, the authorization page will request all scopes selected on the Permissions tab. Read about scopes in the OAuth Guide.

include_granted_scopes String? This parameter is optional. If set to user, Dropbox will return the currently requested scopes as well as all previously granted user scopes for the user. If set to team , Dropbox will return the currently requested scopes as well as all previously granted team scopes for the team. The request will fail if this parameter is provided but not set to user or team, or if it is set to user but the scope contains team scope, or if it is set to team but the authorizing user is not a team admin. If not set, Dropbox will return only the scopes requested in the scope parameter.

token_access_type String? If this parameter is set to offline, then the access token payload returned by a successful /oauth2/token call will contain a short-lived access_token and a long-lived refresh_token that can be used to request a new short-lived access token as long as a user's approval remains valid. If set to online then only a short-lived access_token will be returned. If omitted, the response will default to returning a long-lived access_token if they are allowed in the app console. If long-lived access tokens are disabled in the app console, this parameter defaults to online

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.

code_challenge String?(min_length=43, max_length=128) Part of the PKCE flow, the challenge should be an SHA-256 (S256) encoded value of a string that will serve as the code_verifier of the corresponding /oauth2/token call. Can can also be set to plain (plain).

code_challenge_method String? Defines the code challenge method. Can be set to S256 (recommended) or plain.

require_role String? If this parameter is specified, the user will be asked to authorize with a particular type of Dropbox account, either work for a team account or personal for a personal account. Your app should still verify the type of Dropbox account after authorization since the user could modify or remove the require_role parameter.

force_reapprove Boolean? Whether or not to force the user to approve the app again if they've already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If true, the user will not be automatically redirected and will have to approve the app again.

disable_signup Boolean? When true (default is false) users will not be able to sign up for a Dropbox account via the authorization page. Instead, the authorization page will show a link to the Dropbox iOS app in the App Store. This is only intended for use when necessary for compliance with App Store policies.

locale String? If the locale specified is a supported language, Dropbox will direct users to a translated version of the authorization website. Locale tags should be IETF language tags.

force_reauthentication Boolean? When true (default is false) users will be signed out if they are currently signed in. This will make sure the user is brought to a page where they can create a new account or sign in to another account. This should only be used when there is a definite reason to believe that the user needs to sign in to a new or different account.

Returns

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

Code flow and PKCE flow

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

code String The authorization code, which can be used to attain a bearer token by calling /oauth2/token.

state String The state content, if any, originally passed to /oauth2/authorize.

Sample response

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

Token flow

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

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

access_token String A token which can be used to make calls to the Dropbox API.

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_description String A user-friendly description of the error that occurred.

state String The state content, if any, originally passed to /oauth2/authorize.

/oauth2/token

Description

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

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

URL Structure

https://api.dropboxapi.com/oauth2/token

Method

POST

Example

Example: access token request in code flow

curl https://api.dropbox.com/oauth2/token \     -d code=<AUTHORIZATION_CODE> \     -d grant_type=authorization_code \     -d redirect_uri=<REDIRECT_URI> \     -u <APP_KEY>:<APP_SECRET>

Example: refresh token request

curl https://api.dropbox.com/oauth2/token \     -d grant_type=refresh_token \     -d refresh_token=<REFRESH_TOKEN> \     -u <APP_KEY>:<APP_SECRET>

Example: PKCE code flow token request

curl https://api.dropbox.com/oauth2/token \     -d code=<AUTHORIZATION_CODE> \     -d grant_type=authorization_code \     -d redirect_uri=<REDIRECT_URI> \     -d code_verifier=<VERIFICATION_CODE> \     -d client_id=<APP_KEY>

Parameters

code String The code acquired by directing users to /oauth2/authorize?response_type=code.

grant_type String The grant type, which must be authorization_code for completing a code flow or refresh_token for using a refresh token to get a new access token.

refresh_token String? A unique, long-lived token that can be used to request new short-lived access tokens without direct interaction from a user in your app.

client_id String? If credentials are passed in POST parameters, this parameter should be present and should be the app's key (found in the App Console).

client_secret String? If credentials are passed in POST parameters, this parameter should be present and should be the app's secret.

redirect_uri String? The redirect URI used to receive the authorization code from /oauth2/authorize, if provided. Only used to validate it matches the redirect URI supplied to /oauth2/authorize for the current authorization code. It is not used to redirect again.

code_verifier String?(min_length=43, max_length=128) The client-generated string used to verify the encrypted code_challenge used in the Authorization URL.

Returns

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

When input grant_type=authorization_code:

access_token String The access token to be used to call the Dropbox API.

expires_in String The length of time in seconds that the access token will be valid for.

token_type String Will always be bearer.

scope String The permission set applied to the token.

account_id String An API v2 account ID if this OAuth2 flow is user-linked.

team_id String An API v2 team ID if this OAuth 2 flow is team-linked.

refresh_token String If the token_access_type was set to offline when calling /oauth2/authorize, then response will include a refresh token. This refresh token is long-lived and won't expire automatically. It can be stored and re-used multiple times.

uid String The API v1 identifier value. It is deprecated and should no longer be used.

Sample response

Example: short-lived token

{   "access_token": "sl.AbX9y6Fe3AuH5o66-gmJpR032jwAwQPIVVzWXZNkdzcYT02akC2de219dZi6gxYPVnYPrpvISRSf9lxKWJzYLjtMPH-d9fo_0gXex7X37VIvpty4-G8f4-WX45AcEPfRnJJDwzv-",   "expires_in": "13220",   "token_type": "bearer",   "scope": "account_info.read files.content.read files.content.write files.metadata.read",   "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",   "uid": "12345", }

Example: short-lived "offline" access token

{   "access_token": "sl.abcd1234efg",   "expires_in": "13220",   "token_type": "bearer",   "scope": "account_info.read files.content.read files.content.write files.metadata.read",   "refresh_token": "AAEVvIKp9ApA9wkdE",   "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",   "uid": "12345", }

Example: legacy token

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

When input grant_type=refresh_token:

Use the refresh token to get a new access token. This request won't return a new refresh token since refresh tokens don't expire automatically and can be reused repeatedly.

access_token String The access token to be used to call the Dropbox API.

expires_in String The length of time in seconds that the access token will be valid for.

token_type String Will always be bearer.

Example:

{   "access_token": "sl.abcd1234efg",   "expires_in": "13220",   "token_type": "bearer",   }

Errors

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

Errors by status code

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

Endpoint-specific errors (409)

The following table describes the top-level JSON object attributes present in the body of 409 responses.

Key	Description
error	A value that conforms to the error data type schema defined in the definition of each route.
error_summary	A string that summarizes the value of the "error" key. It is a concatenation of the hierarchy of union tags that make up the error. This provides a human-readable error string, and can also be used for simple programmatic error handling via prefix matching. To disincentivize exact string matching, we append a random number of "." characters at the end of the string.
user_message	An optional field. If present, it includes a message that can be shown directly to the end user of your app. You should show this message if your app is unprepared to programmatically handle the error returned by an endpoint.

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.

account

/set_profile_photo

Version

Description

Sets a user's profile photo.

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

URL Structure

https://api.dropboxapi.com/2/account/set_profile_photo

Authentication

User Authentication

Endpoint format

RPC

Required Scope

account_info.write

Example

curl -X POST https://api.dropboxapi.com/2/account/set_profile_photo \     --header "Authorization: Bearer                            " \     --header "Content-Type: application/json" \     --data "{\"photo\": {\".tag\": \"base64_data\",\"base64_data\": \"SW1hZ2UgZGF0YSBpbiBiYXNlNjQtZW5jb2RlZCBieXRlcy4gTm90IGEgdmFsaWQgZXhhbXBsZS4=\"}}"

Parameters

{     "photo": {         ".tag": "base64_data",         "base64_data": "SW1hZ2UgZGF0YSBpbiBiYXNlNjQtZW5jb2RlZCBieXRlcy4gTm90IGEgdmFsaWQgZXhhbXBsZS4="     } }

photo PhotoSourceArg Image to set as the user's new profile photo.

PhotoSourceArg (open union)

The value will be one of the following datatypes. New values may be introduced as our API evolves.

base64_data String Image data in base64-encoded bytes.

Returns

{     "profile_photo_url": "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102\u0026size=128x128" }

profile_photo_url String URL for the photo representing the user, if one is set.

Errors

{     "error_summary": "file_type_error/...",     "error": {         ".tag": "file_type_error"     } }

{     "error_summary": "file_size_error/...",     "error": {         ".tag": "file_size_error"     } }

{     "error_summary": "dimension_error/...",     "error": {         ".tag": "dimension_error"     } }

{     "error_summary": "thumbnail_error/...",     "error": {         ".tag": "thumbnail_error"     } }

{     "error_summary": "transient_error/...",     "error": {         ".tag": "transient_error"     } }

{     "error_summary": "other/...",     "error": {         ".tag": "other"     } }

SetProfilePhotoError (open union)

The value will be one of the following datatypes. New values may be introduced as our API evolves.

file_type_error Void File cannot be set as profile photo.

file_size_error Void File cannot exceed 10 MB.

dimension_error Void Image must be larger than 128 x 128.

thumbnail_error Void Image could not be thumbnailed.

transient_error Void Temporary infrastructure failure, please retry.

auth

/token/from_oauth1

Version

Description

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

URL Structure

https://api.dropboxapi.com/2/auth/token/from_oauth1

Authentication

App Authentication

Endpoint format

RPC

Required Scope

None

Example

Get app key and secret for:

curl -X POST https://api.dropboxapi.com/2/auth/token/from_oauth1 \     --header "Authorization: Basic                            " \     --header "Content-Type: application/json" \     --data "{\"oauth1_token\": \"qievr8hamyg6ndck\",\"oauth1_token_secret\": \"qomoftv0472git7\"}"

Parameters

{     "oauth1_token": "qievr8hamyg6ndck",     "oauth1_token_secret": "qomoftv0472git7" }

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

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

{     "error_summary": "app_id_mismatch/...",     "error": {         ".tag": "app_id_mismatch"     } }

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

Version

Description

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

URL Structure

https://api.dropboxapi.com/2/auth/token/revoke

Authentication

User Authentication

Endpoint format

RPC

Required Scope

None

Example

curl -X POST https://api.dropboxapi.com/2/auth/token/revoke \     --header "Authorization: Bearer                            "

Parameters

No parameters.

Returns

No return values.

Errors

No errors.

check

/app

Version: PREVIEW - may change or disappear without notice

Description

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

URL Structure

https://api.dropboxapi.com/2/check/app

Authentication

App Authentication

Endpoint format

RPC

Required Scope

None

Example

Get app key and secret for:

curl -X POST https://api.dropboxapi.com/2/check/app \     --header "Authorization: Basic                            " \     --header "Content-Type: application/json" \     --data "{\"query\": \"foo\"}"

Parameters

{     "query": "foo" }

EchoArg contains the arguments to be sent to the Dropbox servers.

query String The string that you'd like to be echoed back to you. The default for this field is "".

Returns

{     "result": "foo" }

EchoResult contains the result returned from the Dropbox servers.

result String If everything worked correctly, this would be the same as query. The default for this field is "".

Errors

No errors.

/user

Version: PREVIEW - may change or disappear without notice

Description

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

URL Structure

https://api.dropboxapi.com/2/check/user

Authentication

User Authentication

Endpoint format

RPC

Required Scope

account_info.read

Example

curl -X POST https://api.dropboxapi.com/2/check/user \     --header "Authorization: Bearer                            " \     --header "Content-Type: application/json" \     --data "{\"query\": \"foo\"}"

Parameters

{     "query": "foo" }

EchoArg contains the arguments to be sent to the Dropbox servers.

query String The string that you'd like to be echoed back to you. The default for this field is "".

Returns

{     "result": "foo" }

EchoResult contains the result returned from the Dropbox servers.

result String If everything worked correctly, this would be the same as query. The default for this field is "".

Errors

No errors.

file_properties

This namespace contains helpers for property and template metadata endpoints.

These endpoints enable you to tag arbitrary key/value data to Dropbox files.

The most basic unit in this namespace is the :type:\`PropertyField\`. These fields encapsulate the actual key/value data.

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

The :type:\`PropertyGroupTemplate\` is a way of restricting the possible key names and value types of the data within a property group. The possible key names and value types are explicitly enumerated using :type:\`PropertyFieldTemplate\` objects.

You can think of a property group template as a class definition for a particular key/value metadata object, and the property groups themselves as the instantiations of these objects.

Templates are owned either by a user/app pair or team/app pair. Templates and their associated properties can't be accessed by any app other than the app that created them, and even then, only when the app is linked with the owner of the template (either a user or team).

User-owned templates are accessed via the user-auth file_properties/templates/*_for_user endpoints, while team-owned templates are accessed via the team-auth file_properties/templates/*_for_team endpoints. Properties associated with either type of template can be accessed via the user-auth properties/* endpoints.

Finally, properties can be accessed from a number of endpoints that return metadata, including \`files/get_metadata\`, and \`files/list_folder\`. Properties can also be added during upload, using \`files/upload\`.

/properties/add

Version

Description

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

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

URL Structure

https://api.dropboxapi.com/2/file_properties/properties/add

Authentication

User Authentication

Endpoint format

RPC

Required Scope

files.metadata.write

Example

curl -X POST https://api.dropboxapi.com/2/file_properties/properties/add \     --header "Authorization: Bearer                            " \     --header "Content-Type: application/json" \     --data "{\"path\": \"/my_awesome/word.docx\",\"property_groups\": [{\"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\",\"fields\": [{\"name\": \"Security Policy\",\"value\": \"Confidential\"}]}]}"

Parameters

{     "path": "/my_awesome/word.docx",     "property_groups": [         {             "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",             "fields": [                 {                     "name": "Security Policy",                     "value": "Confidential"                 }             ]         }     ] }

path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file or folder.

property_groups List of (PropertyGroup) The property groups which are to be added to a Dropbox file. No two groups in the input should refer to the same template.

A subset of the property fields described by the corresponding PropertyGroupTemplate. Properties are always added to a Dropbox file as a PropertyGroup. The possible key names and value types in this group are defined by the corresponding PropertyGroupTemplate.

template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.

fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.

Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup.

name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.

value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.

Returns

No return values.

Errors

Example: restricted_content

{     "error_summary": "restricted_content/...",     "error": {         ".tag": "restricted_content"     } }

{     "error_summary": "other/...",     "error": {         ".tag": "other"     } }

Example: unsupported_folder

{     "error_summary": "unsupported_folder/...",     "error": {         ".tag": "unsupported_folder"     } }

Example: property_field_too_large

{     "error_summary": "property_field_too_large/...",     "error": {         ".tag": "property_field_too_large"     } }

Example: does_not_fit_template

{     "error_summary": "does_not_fit_template/...",     "error": {         ".tag": "does_not_fit_template"     } }

Example: duplicate_property_groups

{     "error_summary": "duplicate_property_groups/...",     "error": {         ".tag": "duplicate_property_groups"     } }

Example: property_group_already_exists

{     "error_summary": "property_group_already_exists/...",     "error": {         ".tag": "property_group_already_exists"     } }

AddPropertiesError (union)

The value will be one of the following datatypes:

template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.

restricted_content Void You do not have permission to modify this template.

path LookupError

The value will be one of the following datatypes. New values may be introduced as our API evolves.

not_found Void There is nothing at the given path.

not_file Void We were expecting a file, but the given path refers to something that isn't a file.

not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.

restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.

unsupported_folder Void This folder cannot be tagged. Tagging folders is not supported for team-owned templates.

property_field_too_large Void One or more of the supplied property field values is too large.

does_not_fit_template Void One or more of the supplied property fields does not conform to the template specifications.

duplicate_property_groups Void There are 2 or more property groups referring to the same templates in the input.

property_group_already_exists Void A property group associated with this template and file already exists.

/properties/overwrite

Version

Description

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

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

URL Structure

https://api.dropboxapi.com/2/file_properties/properties/overwrite

Authentication

User Authentication

Endpoint format

RPC

Required Scope

files.metadata.write

Example

curl -X POST https://api.dropboxapi.com/2/file_properties/properties/overwrite \     --header "Authorization: Bearer                            " \     --header "Content-Type: application/json" \     --data "{\"path\": \"/my_awesome/word.docx\",\"property_groups\": [{\"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\",\"fields\": [{\"name\": \"Security Policy\",\"value\": \"Confidential\"}]}]}"

Parameters

{     "path": "/my_awesome/word.docx",     "property_groups": [         {             "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",             "fields": [                 {                     "name": "Security Policy",                     "value": "Confidential"                 }             ]         }     ] }

OverwritePropertyGroupArg

path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file or folder.

property_groups List of (PropertyGroup, min_items=1) The property groups "snapshot" updates to force apply. No two groups in the input should refer to the same template.

template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.

fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.

Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup.

name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.

value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.

Returns

No return values.

Errors

Example: restricted_content

{     "error_summary": "restricted_content/...",     "error": {         ".tag": "restricted_content"     } }

{     "error_summary": "other/...",     "error": {         ".tag": "other"     } }

Example: unsupported_folder

{     "error_summary": "unsupported_folder/...",     "error": {         ".tag": "unsupported_folder"     } }

Example: property_field_too_large

{     "error_summary": "property_field_too_large/...",     "error": {         ".tag": "property_field_too_large"     } }

Example: does_not_fit_template

{     "error_summary": "does_not_fit_template/...",     "error": {         ".tag": "does_not_fit_template"     } }

Example: duplicate_property_groups

{     "error_summary": "duplicate_property_groups/...",     "error": {         ".tag": "duplicate_property_groups"     } }

InvalidPropertyGroupError (union)

The value will be one of the following datatypes:

template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.

restricted_content Void You do not have permission to modify this template.

path LookupError

The value will be one of the following datatypes. New values may be introduced as our API evolves.

not_found Void There is nothing at the given path.

not_file Void We were expecting a file, but the given path refers to something that isn't a file.

not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.

restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.

unsupported_folder Void This folder cannot be tagged. Tagging folders is not supported for team-owned templates.

property_field_too_large Void One or more of the supplied property field values is too large.

does_not_fit_template Void One or more of the supplied property fields does not conform to the template specifications.

duplicate_property_groups Void There are 2 or more property groups referring to the same templates in the input.

/properties/remove

Version

Description

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

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

URL Structure

https://api.dropboxapi.com/2/file_properties/properties/remove

Authentication

User Authentication

Endpoint format

RPC

Required Scope

files.metadata.write

Example

curl -X POST https://api.dropboxapi.com/2/file_properties/properties/remove \     --header "Authorization: Bearer                            " \     --header "Content-Type: application/json" \     --data "{\"path\": \"/my_awesome/word.docx\",\"property_template_ids\": [\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"]}"

Parameters

{     "path": "/my_awesome/word.docx",     "property_template_ids": [         "ptid:1a5n2i6d3OYEAAAAAAAAAYa"     ] }

path String(pattern="/(.|[\r\n])*|id:.*|(ns:[0-9]+(/.*)?)") A unique identifier for the file or folder.

property_template_ids List of (String(min_length=1, pattern="(/|ptid:).*")) A list of identifiers for a template created by templates/add_for_user or templates/add_for_team.

Returns

No return values.

Errors

Example: restricted_content

{     "error_summary": "restricted_content/...",     "error": {         ".tag": "restricted_content"     } }

{     "error_summary": "other/...",     "error": {         ".tag": "other"     } }

Example: unsupported_folder

{     "error_summary": "unsupported_folder/...",     "error": {         ".tag": "unsupported_folder"     } }

RemovePropertiesError (union)

The value will be one of the following datatypes:

template_not_found String(min_length=1, pattern="(/|ptid:).*") Template does not exist for the given identifier.

restricted_content Void You do not have permission to modify this template.

path LookupError

The value will be one of the following datatypes. New values may be introduced as our API evolves.

not_found Void There is nothing at the given path.

not_file Void We were expecting a file, but the given path refers to something that isn't a file.

not_folder Void We were expecting a folder, but the given path refers to something that isn't a folder.

restricted_content Void The file cannot be transferred because the content is restricted. For example, sometimes there are legal restrictions due to copyright claims.

unsupported_folder Void This folder cannot be tagged. Tagging folders is not supported for team-owned templates.

property_group_lookup LookUpPropertiesError

LookUpPropertiesError (open union)

The value will be one of the following datatypes. New values may be introduced as our API evolves.

property_group_not_found Void No property group was found.

/properties/search

Version

Description

Search across property templates for particular property field values.

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

URL Structure

https://api.dropboxapi.com/2/file_properties/properties/search

Authentication

User Authentication

Endpoint format

RPC

Required Scope

files.metadata.read

Example

curl -X POST https://api.dropboxapi.com/2/file_properties/properties/search \     --header "Authorization: Bearer                            " \     --header "Content-Type: application/json" \     --data "{\"queries\": [{\"query\": \"Confidential\",\"mode\": {\".tag\": \"field_name\",\"field_name\": \"Security\"},\"logical_operator\": \"or_operator\"}],\"template_filter\": \"filter_none\"}"

Parameters

{     "queries": [         {             "query": "Confidential",             "mode": {                 ".tag": "field_name",                 "field_name": "Security"             },             "logical_operator": "or_operator"         }     ],     "template_filter": "filter_none" }

queries List of (PropertiesSearchQuery, min_items=1) Queries to search.

query String The property field value for which to search across templates.

mode PropertiesSearchMode The mode with which to perform the search.

PropertiesSearchMode (open union)

The value will be one of the following datatypes. New values may be introduced as our API evolves.

field_name String Search for a value associated with this field name.

logical_operator LogicalOperator The logical operator with which to append the query. The default for this union is or_operator.

LogicalOperator (open union)

Logical operator to join search queries together. The value will be one of the following datatypes. New values may be introduced as our API evolves.

or_operator Void Append a query with an "or" operator.

template_filter TemplateFilter Filter results to contain only properties associated with these template IDs. The default for this union is filter_none.

The value will be one of the following datatypes:

filter_some List of (String(min_length=1, pattern="(/|ptid:).*"), min_items=1) Only templates with an ID in the supplied list will be returned (a subset of templates will be returned).

filter_none Void No templates will be filtered from the result (all templates will be returned).

Returns

{     "matches": [         {             "id": "id:a4ayc_80_OEAAAAAAAAAXz",             "path": "/my_awesome/word.docx",             "is_deleted": false,             "property_groups": [                 {                     "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",                     "fields": [                         {                             "name": "Security Policy",                             "value": "Confidential"                         }                     ]                 }             ]         }     ] }

matches List of (PropertiesSearchMatch) A list (possibly empty) of matches for the query.

id String(min_length=1) The ID for the matched file or folder.

path String The path for the matched file or folder.

is_deleted Boolean Whether the file or folder is deleted.

property_groups List of (PropertyGroup) List of custom property groups associated with the file.

template_id String(min_length=1, pattern="(/|ptid:).*") A unique identifier for the associated template.

fields List of (PropertyField) The actual properties associated with the template. There can be up to 32 property types per template.

Raw key/value data to be associated with a Dropbox file. Property fields are added to Dropbox files as a PropertyGroup.

name String Key of the property field associated with a file and template. Keys can be up to 256 bytes.

value String Value of the property field associated with a file and template. Values can be up to 1024 bytes.

cursor String(min_length=1)? Pass the cursor into properties/search/continue to continue to receive search results. Cursor will be null when there are no more results. This field is optional.

Errors

PropertiesSearchError (open union)

The value will be one of the following datatypes. New values may be introduced as our API evolves.

property_group_lookup LookUpPropertiesError

LookUpPropertiesError (open union)

The value will be one of the following datatypes. New values may be introduced as our API evolves.

property_group_not_found Void No property group was found.

/properties/search/continue

Version

Description

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

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

URL Structure

https://api.dropboxapi.com/2/file_properties/properties/search/continue

Authentication

User Authentication

Endpoint format

RPC

Required Scope

files.metadata.read

Example

curl -X POST https://api.dropboxapi.com/2/file_properties/properties/search/continue \     --header "Authorization: Bearer                            " \     --header "Content-Type: application/json" \     --data "{\"cursor\": \"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"}"

Parameters

{     "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu" }

PropertiesSearchContinueArg

cursor String(min_length=1) The cursor returned by your last call to properties/search or properties/search/continue.

Returns

{     "matches": [         {             "id": "id:a4ayc_80_OEAAAAAAAAAXz",             "path": "/my_awesome/word.docx",             "is_deleted": false,             "property_groups": [                 {                     "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa",                     "fields": [                         {                             "name": "Security Policy",                             "value": "Confidential"                         }                     ]                 }             ]         }     ] }