REST API

Step 1 of authentication. Obtain an OAuth request token to be used for the rest of the authentication process.

This method corresponds to Obtaining an Unauthorized Request Token in the OAuth Core 1.0 specification.

https://api.dropbox.com/1/oauth/request_token

There are no Dropbox-specific parameters for this method. See Consumer Obtains a Request Token in the OAuth Core 1.0 specification for a description of the OAuth parameters used for fetching a request token. Since this method is on behalf of an unauthenticated user, no access token or secret should be involved when signing or sending the request.

A request token and the corresponding request token secret, URL-encoded. This token/secret pair is meant to be used with /oauth/access_token to complete the authentication process and cannot be used for any other API calls. See Service Provider Issues an Unauthorized Request Token in the OAuth Core 1.0 specification for additional discussion of the values returned when fetching a request token.

Sample response

oauth_token_secret=b9q1n5il4lcc&oauth_token=mh7an9dkrg59

Step 2 of authentication. Applications should direct the user to /oauth/authorize. This isn't an API call per se, but rather a web endpoint that lets the user log in to Dropbox and choose whether to grant the application the ability to access files on their behalf. The page served by /oauth/authorize should be presented to the user through their web browser. Without the user's authorization in this step, it isn't possible for your application to obtain an access token from /oauth/access_token.

This method corresponds to Obtaining User Authorization in the OAuth Core 1.0 specification.

https://www.dropbox.com/1/oauth/authorize

Note: This is the only step that requires an endpoint on www.dropbox.com. All other API requests are done via api.dropbox.com or api-content.dropbox.com. For security's sake, please do not embed this webpage in your web app (e.g. via an iframe). The user must be redirected to the Dropbox website over HTTPS for unhindered and untampered authorization. As soon as authorization is accepted, the user will be redirected back to your website or to the website specified using oauth_callback (more on that below). If the user declines to authorize your app, no redirect to your site will happen.

• oauth_token - Required. The request token obtained via /oauth/request_token.
• oauth_callback - After the user authorizes an application, the user is redirected to the application-served URL provided by this parameter.
• locale - If the locale specified is a supported language, Dropbox will direct users to a translated version of the authorization website. See the notes above for more information about supported locales.

Because the application doesn't call /oauth/authorize directly, there is no direct return value. After the user authorizes the application, use its request token to retrieve an access token via the /oauth/access_token API call. If the oauth_callback parameter is omitted, the application must find some other way of determining when the authorization step is complete. For example, the application can have the user explicitly indicate to it that this step is complete, but this flow may be less intuitive for users than the redirect flow.

If oauth_callback is specified, the application will know authorization is complete when the user is redirected to the given URL. Dropbox will provide the following return value via GET parameters in the URL:

• oauth_token - The request token that was just authorized. The request token secret isn't sent back.
• uid - The user's unique Dropbox ID.

Step 3 of authentication. After the /oauth/authorize step is complete, the application can call /oauth/access_token to acquire an access token.

This method corresponds to Obtaining an Access Token in the OAuth Core 1.0 specification.

https://api.dropbox.com/1/oauth/access_token

There are no Dropbox-specific parameters for this method. See Consumer Requests an Access Token in the OAuth Core 1.0 specification for a description of the parameters used for fetching an access token. Note that the oauth_token and oauth_token_secret for this method are the request token and request token secret obtained previously via /oauth/request_token.

URL-encoded access token, access token secret, and Dropbox user id. Upon return, the authorization process is now complete and the access token and corresponding secret can be used to sign requests for the main API calls. See Service Provider Grants an Access Token in the OAuth Core 1.0 specification for additional discussion of the values returned when fetching an access token. If your app is configured to work within an app folder, that folder is also created during this step.

Sample response

oauth_token_secret=95grkd9na7hm&oauth_token=ccl4li5n1q9b&uid=100

https://api.dropbox.com/1/account/info

• locale - Use to specify language settings for user error messages and other language specific text. See the notes above for more information about supported locales.

User account information.

Sample JSON response

{
    "referral_link": "https://www.dropbox.com/referrals/r1a2n3d4m5s6t7",
    "display_name": "John P. User",
    "uid": 12345678,
    "country": "US",
    "quota_info": {
        "shared": 253738410565,
        "quota": 107374182400000,
        "normal": 680031877871
    }
}

Return value definitions

https://api-content.dropbox.com/1/files/<root>/<path>

• root - The root relative to which path is specified. Valid values are sandbox and dropbox.
• path - The path to the file you want to retrieve.

• rev - The revision of the file to retrieve. This defaults to the most recent revision.

The specified file's contents at the requested revision.

The HTTP response contains the content metadata in JSON format within an x-dropbox-metadata header.

This method also supports HTTP Range Retrieval Requests to allow retrieving partial file contents.

Uploads a file using PUT semantics. Note that this call goes to the api-content server.

This method is in most cases simpler to use than /files (POST).

https://api-content.dropbox.com/1/files_put/<root>/<path>?param=val

• root - The root relative to which path is specified. Valid values are sandbox and dropbox.
• path - The full path to the file you want to write to. This parameter should not point to a folder.
• param=val - The URL-encoded parameters for this request. They cannot be sent in the request body.

• The body of the request - Required. The file contents to be uploaded. Since the entire PUT/POST body will be treated as the file, any parameters must be passed as part of the request URL. The request URL should be signed just as you would sign any other OAuth request URL.
• locale - The metadata returned on successful upload will have its size field translated based on the given locale.
• overwrite - This value, either true (default) or false, determines what happens when there's already a file at the specified path. If true, the existing file will be overwritten by the new one. If false, the new file will be automatically renamed (for example, test.txt might be automatically renamed to test (1).txt). The new name can be obtained from the returned metadata.
• parent_rev - The revision of the file you're editing. If parent_rev matches the latest version of the file on the user's Dropbox, that file will be replaced. Otherwise, the new file will be automatically renamed (for example, test.txt might be automatically renamed to test (conflicted copy).txt). If you specify a revision that doesn't exist, the file will not save (error 400). Get the most recent rev by performing a call to /metadata.

The metadata for the uploaded file. More information on the returned metadata fields are available here.

Sample JSON response

{
    "size": "225.4KB",
    "rev": "35e97029684fe",
    "thumb_exists": false,
    "bytes": 230783,
    "modified": "Tue, 19 Jul 2011 21:55:38 +0000",
    "path": "/Getting_Started.pdf",
    "is_dir": false,
    "icon": "page_white_acrobat",
    "root": "dropbox",
    "mime_type": "application/pdf",
    "revision": 220823
}

There's a 150MB limit to all uploads through the API. Users looking to upload files larger than 150MB will have to do so through the Dropbox desktop application.

We strongly recommend providing a Content-Length header set to the size of the uploaded file so that the server can verify that it has received the entire file contents.

Uploads a file. Note that this call goes to the api-content server.

We recommend you use /files_put instead due to its simpler interface.

https://api-content.dropbox.com/1/files/<root>/<path>

• root - The root relative to which path is specified. Valid values are sandbox and dropbox.
• path - The path to the folder the file should be uploaded to. This parameter should not point to a file.

• file - Required. The file contents to be uploaded. We require a multipart upload (multipart/form-data), and the filename parameter of this field should be set to the desired destination filename. While signing this request for OAuth, the file parameter should be set to the destination filename, and then switched to the file contents when preparing the multipart request.
• locale - The metadata returned on successful upload will have its size field translated based on the given locale.
• overwrite - This value, either true (default) or false, determines what happens when there's already a file at the specified path. If true, the existing file will be overwritten by the new one. If false, the new file will be automatically renamed (for example, test.txt might be automatically renamed to test (1).txt). The new name can be obtained from the returned metadata.
• parent_rev - The revision of the file you're editing. If parent_rev matches the latest version of the file on the user's Dropbox, that file will be replaced. Otherwise, the new file will be automatically renamed (for example, test.txt might be automatically renamed to test (conflicted copy).txt). If you specify a revision that doesn't exist, the file will not save (error 400). Get the most recent rev by performing a call to /metadata.

The metadata for the uploaded file. More information on the returned metadata fields are available here.

Sample JSON response

{
    "size": "225.4KB",
    "rev": "35e97029684fe",
    "thumb_exists": false,
    "bytes": 230783,
    "modified": "Tue, 19 Jul 2011 21:55:38 +0000",
    "path": "/Getting_Started.pdf",
    "is_dir": false,
    "icon": "page_white_acrobat",
    "root": "dropbox",
    "mime_type": "application/pdf",
    "revision": 220823
}

There's a 150MB limit to all uploads through the API. Users looking to upload files larger than 150MB will have to do so through the Dropbox desktop application.

https://api.dropbox.com/1/metadata/<root>/<path>

• root - The root relative to which path is specified. Valid values are sandbox and dropbox.
• path - The path to the file or folder.

• file_limit - Default is 10,000. When listing a folder, the service will not report listings containing more than the specified amount of files and will instead respond with a 406 (Not Acceptable) status response.
• hash - Each call to /metadata on a folder will return a hash field, generated by hashing all of the metadata contained in that response. On later calls to /metadata, you should provide that value via this parameter so that if nothing has changed, the response will be a 304 (Not Modified) status code instead of the full, potentially very large, folder listing. This parameter is ignored if the specified path is associated with a file or if list=false. A folder shared between two users will have the same hash for each user.
• list - The strings true and false are valid values. true is the default. If true, the folder's metadata will include a contents field with a list of metadata entries for the contents of the folder. If false, the contents field will be omitted.
• include_deleted - If this parameter is set to true, then files and folders that have been deleted will also be included in the metadata call.
• rev - If you include a particular revision number, then only the metadata for that revision will be returned.
• locale - The metadata returned will have its size field translated based on the given locale. For more information see above.

The metadata for the file or folder at the given <path>. If <path> represents a folder and the list parameter is true, the metadata will also include a listing of metadata for the folder's contents.

Sample JSON return value for a file

{
    "size": "225.4KB",
    "rev": "35e97029684fe",
    "thumb_exists": false,
    "bytes": 230783,
    "modified": "Tue, 19 Jul 2011 21:55:38 +0000",
    "path": "/Getting_Started.pdf",
    "is_dir": false,
    "icon": "page_white_acrobat",
    "root": "dropbox",
    "mime_type": "application/pdf",
    "revision": 220823
}

Sample JSON return value for a folder when list parameter is set to true. If list is false the contents key will simply be omitted from the result.

{
    "size": "0 bytes",
    "hash": "37eb1ba1849d4b0fb0b28caf7ef3af52",
    "bytes": 0,
    "thumb_exists": false,
    "rev": "714f029684fe",
    "modified": "Wed, 27 Apr 2011 22:18:51 +0000",
    "path": "/Public",
    "is_dir": true,
    "icon": "folder_public",
    "root": "dropbox",
    "contents": [
        {
            "size": "0 bytes",
            "rev": "35c1f029684fe",
            "thumb_exists": false,
            "bytes": 0,
            "modified": "Mon, 18 Jul 2011 20:13:43 +0000",
            "path": "/Public/latest.txt",
            "is_dir": false,
            "icon": "page_white_text",
            "root": "dropbox",
            "mime_type": "text/plain",
            "revision": 220191
        }
    ],
    "revision": 29007
}

Return value definitions

Note: modified, rev, and revision aren't returned in the metadata for the root/top-level path.

Obtains metadata for the previous revisions of a file.

Only revisions up to thirty days old are available (or more if the Dropbox user has Pack-Rat). You can use the revision number in conjunction with the /restore call to revert the file to its previous state.

https://api.dropbox.com/1/revisions/<root>/<path>

• root - The root relative to which path is specified. Valid values are sandbox and dropbox.
• path - The path to the file.

• rev_limit - Default is 10. Max is 1,000. When listing a file, the service will not report listings containing more than the amount specified and will instead respond with a 406 (Not Acceptable) status response.
• locale - The metadata returned will have its size field translated based on the given locale. For more information see above.

A list of all revisions formatted just like file metadata. More information on the returned metadata fields are available here.

Sample JSON return value

[
{
    "is_deleted": true,
    "revision": 4,
    "rev": "40000000d",
    "thumb_exists": false,
    "bytes": 0,
    "modified": "Wed, 20 Jul 2011 22:41:09 +0000",
    "path": "/hi2",
    "is_dir": false,
    "icon": "page_white",
    "root": "app_folder",
    "mime_type": "application/octet-stream",
    "size": "0 bytes"
},
{
    "revision": 1,
    "rev": "10000000d",
    "thumb_exists": false,
    "bytes": 3,
    "modified": "Wed, 20 Jul 2011 22:40:43 +0000",
    "path": "/hi2",
    "is_dir": false,
    "icon": "page_white",
    "root": "app_folder",
    "mime_type": "application/octet-stream",
    "size": "3 bytes"
}
]

Restores a file path to a previous revision.

Unlike downloading a file at a given revision and then re-uploading it, this call is atomic. It also saves a bunch of bandwidth.

https://api.dropbox.com/1/restore/<root>/<path>

• root - The root relative to which path is specified. Valid values are sandbox and dropbox.
• path - The path to the file.

• rev - Required. The revision of the file to restore.
• locale - The metadata returned will have its size field translated based on the given locale. For more information see above.

The metadata of the restored file. More information on the returned metadata fields are available here.

Sample JSON response

{
    "is_deleted": true,
    "revision": 4,
    "rev": "40000000d",
    "thumb_exists": false,
    "bytes": 0,
    "modified": "Wed, 20 Jul 2011 22:41:09 +0000",
    "path": "/hi2",
    "is_dir": false,
    "icon": "page_white",
    "root": "sandbox",
    "mime_type": "application/octet-stream",
    "size": "0 bytes"
}

Returns metadata for all files and folders that match the search query.

Searches are limited to the folder path and its sub-folder hierarchy provided in the call.

https://api.dropbox.com/1/search/<root>/<path>

• root - The root relative to which path is specified. Valid values are sandbox and dropbox.
• path - The path to the folder you want to search from.

• query - Required. The search string. Must be at least three characters long.
• file_limit - The maximum and default value is 1,000. No more than file_limit search results will be returned.
• include_deleted - If this parameter is set to true, then files and folders that have been deleted will also be included in the search.
• locale - The metadata returned will have its size field translated based on the given locale. For more information see above.

List of metadata entries for any matching files and folders. More information on the returned metadata fields are available here.

Sample JSON return value for a search for .txt in Dropbox/Public folder

[
    {
        "size": "0 bytes",
        "rev": "35c1f029684fe",
        "thumb_exists": false,
        "bytes": 0,
        "modified": "Mon, 18 Jul 2011 20:13:43 +0000",
        "path": "/Public/latest.txt",
        "is_dir": false,
        "icon": "page_white_text",
        "root": "dropbox",
        "mime_type": "text/plain",
        "revision": 220191
    }
]

Creates and returns a shareable link to files or folders.

Note: Links created by the /shares API call expire after thirty days.

https://api.dropbox.com/1/shares/<root>/<path>

• root - The root relative to which path is specified. Valid values are sandbox and dropbox.
• path - The path to the file or folder you want a sharable link to.

• locale - Use to specify language settings for user error messages and other language specific text. See the notes above for more information about supported locales.

A shareable link to the file or folder. The link can be used publicly and directs to a preview page of the file. Also returns the link's expiration date in Dropbox's usual date format.

Sample JSON return value for a file

{
    "url": "http://db.tt/APqhX1",
    "expires": "Wed, 17 Aug 2011 02:34:33 +0000"
}

Returns a link directly to a file.

Similar to /shares. The difference is that this bypasses the Dropbox webserver, used to provide a preview of the file, so that you can effectively stream the contents of your media.

https://api.dropbox.com/1/media/<root>/<path>

• root - The root relative to which path is specified. Valid values are sandbox and dropbox.
• path - The path to the media file you want a direct link to.

• locale - Use to specify language settings for user error messages and other language specific text. See the notes above for more information about supported locales.

A url that serves the media directly. Also returns the link's expiration date in Dropbox's usual date format.

Sample JSON return value for a file

{
    'url': 'http://www.dropbox.com/s/m/a2mbDa2',
    'expires': 'Fri, 16 Sep 2011 01:01:25 +0000'
}

https://api-content.dropbox.com/1/thumbnails/<root>/<path>

• root - The root relative to which path is specified. Valid values are sandbox and dropbox.
• path - The path to the image file you want to thumbnail.

• format - JPEG (default) or PNG. For images that are photos, JPEG should be preferred, while PNG is better for screenshots and digital art.

• size - One of the following values (default small):

  value	dimensions (px)
  small	32x32
  medium	64x64
  large	128x128
  s	64x64
  m	128x128
  l	640x480
  xl	1024x768

A thumbnail of the specified image's contents.

The HTTP response contains the content metadata in JSON format within an x-dropbox-metadata header.

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 will not be converted to a thumbnail.