How to Use Google Workspace Drive API to Manage File Revisions

Google Docs, Sheets, and Slides are famous for their seamless version history. Every time a user makes an edit, Google quietly saves a snapshot in the background. But what about non-Google files, like a massive Photoshop .psd or an AutoCAD file stored in Google Drive? If a user uploads a new version of the file with the exact same name, Drive normally replaces the old file but retains the previous version in the background. If you are building a custom backup script or an auditing tool via the Google Drive API, you must know how to interact with the Revisions resource to track, download, or permanently delete these historical versions.

Understanding the Revisions Resource

In the Drive API, a Revision is a sub-resource attached to a specific File ID. You cannot query all revisions across the entire drive at once; you must query the revisions for a specific file.

Crucial note: Google automatically merges and deletes older revisions of native Google Docs to save space. However, for binary files (like PDFs or MP4s), Google keeps the revisions indefinitely, and they count against the user’s storage quota. If a user uploads a 1GB video file 10 times, it consumes 10GB of their Drive quota.

Step 1: List All Revisions of a File

To see the history of a file, you use the revisions().list() method. You must provide the fileId.

Here is an example using the official Google API Client Library for Python:

file_id = '1aB2c3D4e5F6g7H8i9J0'

# Request the list of revisions
revisions_response = service.revisions().list(
    fileId=file_id,
    fields='revisions(id, modifiedTime, originalFilename, size)'
).execute()

revisions = revisions_response.get('revisions', [])

for rev in revisions:
    print(f"Rev ID: {rev['id']} | Date: {rev['modifiedTime']} | Size: {rev.get('size', 'N/A')}")

Notice we use the fields parameter to extract specific metadata. The id of a revision is usually a short string of numbers (e.g., 1, 2, 3) rather than a long UUID.

Step 2: Download a Specific Historical Revision

If an employee accidentally overwrote a crucial contract PDF and you need to restore yesterday’s version via the API, you must use the revisions().get() method.

Because you are downloading actual file content (not just metadata), you must include the alt=media parameter.

import io
from googleapiclient.http import MediaIoBaseDownload

revision_id = '2' # The ID of the older version

# Initiate the download request
request = service.revisions().get_media(
    fileId=file_id,
    revisionId=revision_id
)

fh = io.FileIO('restored_contract.pdf', 'wb')
downloader = MediaIoBaseDownload(fh, request)

done = False
while done is False:
    status, done = downloader.next_chunk()
    print(f"Download {int(status.progress() * 100)}%.")

This script streams the historical binary data directly to your local hard drive.

Step 3: Prevent Revisions from Being Deleted

By default, Google Drive may prune older revisions to save space (this behavior varies based on the Workspace tier and file type). If a specific revision is legally required for compliance auditing, you can “pin” it using the keepForever boolean.

# Pin the revision so it is never automatically deleted
service.revisions().update(
    fileId=file_id,
    revisionId=revision_id,
    body={'keepForever': True}
).execute()

Step 4: Delete Revisions to Free Up Storage

If your organization is running out of Google Workspace storage, you can write a script that iterates through large files and permanently deletes old revisions using the revisions().delete() method.

# Permanently delete the revision to reclaim quota
service.revisions().delete(
    fileId=file_id,
    revisionId=revision_id
).execute()

By mastering the Revisions endpoint, you can build powerful disaster recovery workflows and automated storage management tools directly into your Google Workspace environment.