This guide explains how to use the revisions
resource to manage file revisions, such as getting a file revision and
publishing a Google Workspace revision. The Google Drive API also lets you
download revisions. For more details about revision terminology, see Changes
and revisions overview.
To access the revision history, a user must have the role of owner,
organizer, fileOrganizer, or writer.
To specify the fields to return in the response, you can set the fields
system parameter
with any method of the revisions resource. If
you omit the parameter, the server returns a default set of fields. For example,
the revisions.list method only returns the id, mimeType, kind, and
modifiedTime fields. To return different fields, see Return specific fields.
Specify revisions to save from auto delete
Google Drive automatically deletes older revisions that are no longer of interest to the user.
A blob file revision can be set to "Keep Forever" meaning the revision cannot be automatically purged. Up to 200 revisions can be set to "Keep Forever" and they count towards your storage limit. The head revision is never auto-purged.
Any blob file revision, other than the head revision, that's not designated as "Keep Forever" is purgeable. Purgeable revisions are typically preserved for 30 days, but can be purged earlier if a file has 100 revisions that aren't designated as "Keep Forever" and a new revision is uploaded.
You can set the boolean keepForever field of the revisions resource to true to mark revisions that you
don't want Drive to purge. Once a blob file revision is set to
"Keep Forever", it can only be downloaded or deleted. For more information, see
Download a revision or Delete a
revision.
If you're using the older Drive API v2, use the pinned field of the
revisions resource instead of
keepForever.
Get a file revision
To get a file revision's metadata or content, use the get method on the
revisions resource with the fileId and
revisionId path parameters. If you don't know the revision ID, you can list
all revisions on a file using the list method.
The method returns the revision's metadata as an instance of a revisions
resource.
To acknowledge the risk of downloading known malware or other
abusive files, set the
acknowledgeAbuse query parameter to true. This field is only applicable when
the alt=media parameter is set and the user is either the file owner or an
organizer of the shared drive in which the file resides.
List a file's revisions
To list a file's revisions, use the list
method on the revisions resource with the
fileId path parameter. The method returns a list of file revisions.
Pass the following query parameters to customize pagination of, or filter, revisions:
pageSize: The maximum number of revisions to return per page.pageToken: A page token, received from a previous list call. Provide this token to retrieve the subsequent page.
Update a file revision
To update a revision on a file, use the
update method on the revisions resource with the fileId and revisionId path
parameters.
The method returns an instance of a revisions resource.
Download a revision
You can only download blob file content revisions marked as "Keep Forever". If you want to download a revision, make sure to set it to "Keep Forever" first. For more information, see Specify revisions to save from auto delete.
To download a blob file content revision or to export a Google Workspace document content revision, see Download and export files.
Delete a file revision
To permanently delete a file revision, use the
delete method on the revisions resource with the fileId and revisionId path
parameters.
You can only delete revisions for blob files with binary content in Drive, such as images, videos, and PDFs. You can delete a blob file revision when it's marked as "Keep Forever." Revisions for other files, such as a Google Docs or Sheets, and the last remaining revision of the binary file, can't be deleted.
Publish a revision
To publish a Google Docs, Google Sheets, and Google Slides revision, set
the published property for that file in the
revisions resource. This property can't be set
for Google Sites revisions using Drive API.
Published revisions don't reflect changes made to a file unless the
publishAuto property is set. If the property is set to true, newer revisions
of a file are automatically published, overwriting the previous ones.
Slides and Drawings only support automatic
re-publishing and require the publishAuto property to be set to true. For
Sites files, publishAuto is always false.
If the file is created in a Google Workspace domain, the
publishedOutsideDomain property indicates whether the revision is accessible
by anyone or if it's restricted to users of the domain. For Sites
files, this property indicates whether a type=anyone permission exists. For
more information, see the
type field on the
permissions resource.
Automatic publishing is also controlled by the "Automatically republish when changes are made" checkbox in the UI of Docs and Sheets. For more information, see Make Google Docs, Sheets, Slides & Forms public.