Core API

https://api.dropbox.com/1/disable_access_token

An empty JSON dictionary, which indicates success.

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

{
    "uid": 12345678,
    "display_name": "John User",
    "name_details": {
        "familiar_name": "John",
        "given_name": "John",
        "surname": "User"
    },
    "referral_link": "https://www.dropbox.com/referrals/r1a2n3d4m5s6t7",
    "country": "US",
    "locale": "en",
    "is_paired": false,
    "team": {
        "name": "Acme Inc.",
        "team_id": "dbtid:1234abcd"
    },
    "quota_info": {
        "shared": 253738410565,
        "quota": 107374182400000,
        "normal": 680031877871
    }
}

Return value definitions

Downloads a file. Note that this call goes to api-content.dropbox.com instead of api.dropbox.com.

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

• 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 api-content.dropbox.com instead of api.dropbox.com.

The preferred HTTP method for this call is PUT. For compatibility with browser environments, the POST HTTP method is also recognized.

Note: Providing a Content-Length header set to the size of the uploaded file is required so that the server can verify that it has received the entire file contents.

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

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

required The file contents to be uploaded. Since the entire PUT 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 whether an existing file will be overwritten by this upload. If true, any existing file will be overwritten. If false, the other parameters determine whether a conflict occurs and how that conflict is resolved.
• parent_rev If present, this parameter specifies 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, a conflict will occur. (See below.) If you specify a parent_rev and that revision doesn't exist, the file won't save (error 400). You can get the most recent rev by performing a call to /metadata.
• autorename This value, either true (default) or false, determines what happens when there is a conflict. If true, the file being uploaded will be automatically renamed to avoid the conflict. (For example, test.txt might be automatically renamed to test (1).txt.) The new name can be obtained from the returned metadata. If false, the call will fail with a 409 (Conflict) response code.

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
}

/files_put has a maximum file size limit of 150 MB and does not support uploads with chunked encoding. To upload larger files, use /chunked_upload instead.

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

• path The path to the file or folder.

• file_limit Default is 10,000 (max is 25,000). When listing a folder, the service won't 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.
• 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 Only applicable when list is set. If this parameter is set to true, then contents will include the metadata of deleted children. Note that the target of the metadata call is always returned even when it has been deleted (with is_deleted set to true) regardless of this flag.
• 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.
• include_media_info If true, each file will include a photo_info dictionary for photos and a video_info dictionary for videos with additional media info. If the data isn't available yet, the string pending will be returned instead of a dictionary.
• include_membership If true, metadata for a shared folder will include a list of members and a list of groups.

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",
    "client_mtime": "Mon, 18 Jul 2011 18:04:35 +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": "/Photos",
    "is_dir": true,
    "icon": "folder",
    "root": "dropbox",
    "contents": [
        {
            "size": "2.3 MB",
            "rev": "38af1b183490",
            "thumb_exists": true,
            "bytes": 2453963,
            "modified": "Mon, 07 Apr 2014 23:13:16 +0000",
            "client_mtime": "Thu, 29 Aug 2013 01:12:02 +0000",
            "path": "/Photos/flower.jpg",
            "photo_info": {
              "lat_long": [
                37.77256666666666,
                -122.45934166666667
              ],
              "time_taken": "Wed, 28 Aug 2013 18:12:02 +0000"
            },
            "is_dir": false,
            "icon": "page_white_picture",
            "root": "dropbox",
            "mime_type": "image/jpeg",
            "revision": 14511
        }
    ],
    "revision": 29007
}

Return value definitions

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

https://api.dropbox.com/1/delta

• cursor A string that is used to keep track of your current state. On the next call pass in this value to return delta entries that have been recorded since the cursor was returned.
• locale The metadata returned will have its size field translated based on the given locale. For more information see above.
• path_prefix If present, this parameter filters the response to only include entries at or under the specified path. For example, a path_prefix of "/Photos/Vacation" will return entries for the path "/Photos/Vacation" and any files and folders under that path. If you use the path_prefix parameter, you must continue to pass the correct prefix on subsequent calls using the returned cursor. You can switch the path_prefix on any existing cursor to a descendant of the existing path_prefix on subsequent calls to /delta. For example if your cursor has no path_prefix, you can switch to any path_prefix. If your cursor has a path_prefix of "/Photos", you can switch it to "/Photos/Vacaction".
• include_media_info If true, each file will include a photo_info dictionary for photos and a video_info dictionary for videos with additional media info. When include_media_info is specified, files will only appear in delta responses when the media info is ready. If you use the include_media_info parameter, you must continue to pass the same value on subsequent calls using the returned cursor.

A JSON object with four fields:

• entries A list of "delta entries" (described below).
• reset If true, clear your local state before processing the delta entries. reset is always true on the initial call to /delta (i.e. when no cursor is passed in). Otherwise, it is true in rare situations, such as after server or account maintenance, or if a user deletes their app folder.
• cursor A string that encodes the latest information that has been returned. On the next call to /delta, pass in this value.
• has_more If true, then there are more entries available; you can call /delta again immediately to retrieve those entries. If 'false', then wait for at least five minutes (preferably longer) before checking again.

Each delta entry is a 2-item list of one of the following forms:

• [<path>, <metadata>] - Indicates that there is a file/folder at the given path. You should add the entry to your local state. The metadata value is the same as what would be returned by the /metadata call, except folder metadata doesn't have hash or contents fields. To correctly process delta entries:
  • If the new entry includes parent folders that don't yet exist in your local state, create those parent folders in your local state.
  • If the new entry is a file, replace whatever your local state has at path with the new entry.
  • If the new entry is a folder, check what your local state has at <path>. If it's a file, replace it with the new entry. If it's a folder, apply the new <metadata> to the folder, but don't modify the folder's children. If your local state doesn't yet include this path, create it as a folder.
  • If the new entry is a folder with the read-only field set to true, apply the read-only permission recursively to all files within the shared folder.
• [<path>, null] - Indicates that there is no file/folder at the given path. To update your local state to match, anything at path and all its children should be deleted. Deleting a folder in your Dropbox will sometimes send down a single deleted entry for that folder, and sometimes separate entries for the folder and all child paths. If your local state doesn't have anything at path, ignore this entry.

Note: Dropbox treats file names in a case-insensitive but case-preserving way. To facilitate this, the <path> values above are lower-cased versions of the actual path. The last path component of the <metadata> value will be case-preserved.

A way to quickly get a cursor for the server's state, for use with /delta. Unlike /delta, /delta/latest_cursor does not return any entries, so your app will not know about any existing files or folders in the Dropbox account. For example, if your app processes future delta entries and sees that a folder was deleted, your app won't know what files were in that folder. Use this endpoint if your app only needs to know about new files and modifications and doesn't need to know about files that already exist in Dropbox.

If you need to build local state to match the server state in Dropbox, you should instead use /delta.

https://api.dropbox.com/1/delta/latest_cursor

• path_prefix If present, the returned cursor will be encoded with a path_prefix for the specified path for use with /delta.
• include_media_info If true, the returned cursor will be encoded with include_media_info set to true for use with /delta.

A JSON object with one field:

• cursor A string that encodes the latest server state, as would be returned by /delta when has_more is false.

A long-poll endpoint to wait for changes on an account. In conjunction with /delta, this call gives you a low-latency way to monitor an account for file changes.

Note that this call goes to api-notify.dropbox.com instead of api.dropbox.com.

Unlike most other API endpoints, this call does not require OAuth authentication. The passed in cursor can only be acquired via an authenticated call to /delta.

https://api-notify.dropbox.com/1/longpoll_delta

• cursor A delta cursor as returned from a call to /delta. Note that a cursor returned from a call to /delta with include_media_info=true is incompatible with /longpoll_delta and an error will be returned.
• timeout An optional integer indicating a timeout, in seconds. The default value is 30 seconds, which is also the minimum allowed value. The maximum is 480 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 connection will block until there are changes available or a timeout occurs. In both cases, the HTTP status code will be 200, and the response will be a JSON dictionary. The value of the changes field indicates whether new changes are available. If this value is true, you should call /delta to retrieve the changes. If this value is false, it means the call to /longpoll_delta timed out.

If present, the value of the backoff field indicates how many seconds your code should wait before calling /longpoll_delta again.

Sample JSON return value

{"changes": false, "backoff": 60}

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 Packrat). 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/auto/<path>

• path The path to the file.

• rev_limit Default is 10. Max is 1,000. Up to this number of recent revisions will be returned.
• locale The metadata returned will have its size field translated based on the given locale. For more information see above.

A list of 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/auto/<path>

• 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 whose filename contains the given search string as a substring.

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

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

• path The path to the folder you want to search from.

• query required The search string. This string is split (on spaces) into individual words. Files and folders will be returned if they contain all words in the search string.
• 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.
• include_membership If true, metadata for a shared folder will include a list of members and a list of groups.

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 shared link to a file or folder.

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

• path The path to the file or folder you want to 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.
• short_url When true (default), the URL returned will be shortened using the Dropbox URL shortener. If false, the URL will link directly to the file's preview page.

A JSON dictionary containing a shared link as well as information about the link's visibility and expiration. The url field contains the actual shared link URL. The expires field returns the link's expiration in the Dropbox API's usual date format. Dropbox for Business users can set restrictions on shared links; the visibility field indicates what (if any) restrictions are set on this particular link. Possible values include: "PUBLIC" (anyone can view), "TEAM_ONLY" (only the owner's team can view), "PASSWORD" (a password is required), "TEAM_AND_PASSWORD" (a combination of "TEAM_ONLY" and "PASSWORD" restrictions), or "SHARED_FOLDER_ONLY" (only members of the enclosing shared folder can view). Note that other values may be added at any time.

Sample JSON return value for a file

{
    "url": "https://db.tt/c0mFuu1Y",
    "expires": "Tue, 01 Jan 2030 00:00:00 +0000",
    "visibility": "PUBLIC"
}

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. This URL should not be used to display content directly in the browser.

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

• 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": "https://dl.dropboxusercontent.com/1/view/abcdefghijk/example",
    "expires": "Fri, 16 Sep 2011 01:01:25 +0000"
}

Creates and returns a copy_ref to a file. This reference string can be used to copy that file to another user's Dropbox by passing it in as the from_copy_ref parameter on /fileops/copy.

https://api.dropbox.com/1/copy_ref/auto/<path>

• path The path to the file you want a copy_ref to refer to.

A copy_ref to the specified file. For compatibility reasons, it returns the link's expiration date in Dropbox's usual date format. All links are currently set to expire far enough in the future so that expiration is effectively not an issue.

Sample JSON return value for a file

{
    "copy_ref": "z1X6ATl6aWtzOGq0c3g5Ng",
    "expires": "Fri, 31 Jan 2042 21:01:05 +0000"
}

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

• 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: s):

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

A thumbnail of the specified image's contents. The image returned may be larger or smaller than the size requested, depending on the size and aspect ratio of the original image.

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 won't be converted to a thumbnail.

Gets a preview for a file. Note that this call goes to api-content.dropbox.com instead of api.dropbox.com.

https://api-content.dropbox.com/1/previews/auto/<path>

• path The absolute path to the file you want to preview.

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

Data that represents a preview of the file. The Content-Type header will be either application/pdf or text/html. There is a Original-Content-Length header which contains the size of the preview data.

Previews are only generated for the files with the following extensions: .doc, .docx, .docm, .ppt, .pps, .ppsx, .ppsm, .pptx, .pptm, .xls, .xlsx, .xlsm, .rtf, .pdf