Skip to navigation
Dropbox APIUser EndpointsFiles

List Revisions

View as Markdown

Returns revisions for files based on a file path or a file id. The file path or file id is identified from the latest file entry at the given file path or id. This end point allows your app to query either by file path or file id by setting the mode parameter appropriately. In the ListRevisionsMode.path (default) mode, all revisions at the same file path as the latest file entry are returned. If revisions with the same file id are desired, then mode must be set to ListRevisionsMode.id. The ListRevisionsMode.id mode is useful to retrieve revisions for a given file across moves or renames.

Required scope: files.metadata.read

Endpoint format: RPC

Authentication: User, Dropbox-API-Select-Admin (Whole Team)

Authentication

AuthorizationBearer

OAuth 2.0 token issued to a specific user. Use Authorization: Bearer <token>.

Public clients should use the authorization code flow with PKCE (S256).

For background or offline access, send token_access_type=offline during authorization and use the returned refresh token to obtain new access tokens.

You can generate a short-lived access token from the App Console; see Testing with a generated token.

Headers

Dropbox-API-Select-UserstringOptional

Acts on behalf of a team member for supported user-auth operations. Pass a team member ID such as dbmid:.... When used with a team token, that token must also include the team_data.member scope.

Dropbox-API-Select-AdminstringOptional

Acts as the specified team admin for supported user-auth operations. Pass a team member ID for an admin account. When used with a team token, that token must also include the team_data.member scope.

Dropbox-API-Path-RootstringOptional

Scopes path-based operations to a namespace (root). The value is a JSON serialization of the common.PathRoot union: {".tag": "home"}, {".tag": "root", "root": "<namespace_id>"}, or {".tag": "namespace_id", "namespace_id": "<namespace_id>"}. On failure the request returns 422 with a common.PathRootError.

Request

This endpoint expects an object.
pathstringRequiredformat: "\/(.|[\r\n])*|id:.*|(ns:[0-9]+(/(.|[\r\n])*)?)"
The path to the file you want to see the revisions of.
before_revstring or nullOptionalformat: "[0-9a-f]+">=9 characters

If set, ListRevisions will only return revisions prior to before_rev. Can be set using the last revision from a previous call to list_revisions to fetch the next page of revisions. Only supported in path mode.

include_restorable_infobooleanOptionalDefaults to false
If true, each returned revision will include whether that revision can be restored.
limituint64Optional1-100Defaults to 10
The maximum number of revision entries returned.
modeobject or nullOptional
Determines the behavior of the API in listing the revisions for a given file path or id.
Variant:
files.ListRevisionsMode.pathobjectRequired
Returns revisions with the same file path as identified by the latest file entry at the given file path or id.

Response headers

X-Dropbox-Request-IdstringOptional
A unique identifier for the request, useful for debugging and support.

Response

Successful response
entrieslist of objects
The revisions for the file. Only revisions that are not deleted will show up here.
has_moreboolean

If true, then there are more entries available. Call list_revisions again with before_rev equal to the revision of the last returned entry to retrieve the rest.

is_deletedboolean

If the file identified by the latest revision in the response is either deleted or moved. If before_rev is set, this refers to the latest revision of the file older than before_rev.

server_deleteddatetime or nullOptional
The time of deletion if the file was deleted.

Errors

401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error