A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Google Drive API is how an app or AI agent works with a Google account's files: searching and reading documents, creating and uploading new files, organizing them into folders, and sharing them with people. Access is granted through an OAuth token whose scopes decide the reach, from a single file the app created up to every file in the account, so a narrowly scoped agent sees only what it has been given. Drive can also push a notification when a watched file or the account changes, so an integration learns about activity without repeatedly asking.
How an app or AI agent connects to Google Drive determines what it can reach. There is a route for making calls, a route for receiving change notifications, and a hosted server that exposes Drive tools to agents, and each is governed by the access token behind it and the scopes that token carries.
The Drive REST API answers at https://www.googleapis.com/drive/v3 with JSON requests and responses. Uploading or downloading file content uses a separate media URI at https://www.googleapis.com/upload/drive/v3/files. A call authenticates with an OAuth 2.0 access token whose scopes decide what it can reach.
An app opens a notification channel with files.watch or changes.watch and Drive sends an HTTPS POST to the channel's webhook address each time the watched resource changes. Headers like X-Goog-Resource-State name the kind of change, and channels.stop ends a channel early.
Google's official remote Drive MCP server at https://drivemcp.googleapis.com/mcp/v1 lets an agent call Drive through the Model Context Protocol. It is in the Google Workspace Developer Preview Program, and exposes eight tools: search_files, list_recent_files, get_file_metadata, get_file_permissions, read_file_content, download_file_content, create_file, and copy_file. The copy_file tool was added on 21 May 2026.
A user signs in and consents to specific Drive scopes, and the app receives an access token that acts on that user's Drive. The token reaches only what the granted scopes allow, so drive.file confines it to files the app created or the user picked, while drive grants the whole account.
A service account is a non-human identity that authenticates with its own key and acts as itself, which suits server-to-server jobs and a service account's own Drive storage. With domain-wide delegation set up by a Workspace administrator, it can impersonate users in the domain to act on their files.
The Google Drive API is split into areas an agent can act on, like files and folders, sharing permissions, comments and replies, changes, and shared drives. Each area has its own methods, and the scope an agent holds decides whether it sees one app-created file or every file in the account.
List and search files, read a file's metadata or content, create and upload files, update, copy, and delete them, export Google Workspace documents, and empty the trash.
List who a file or shared drive is shared with, read a single permission, and grant, change, or revoke access.
List, read, create, update, and delete comments on a file, and the replies threaded under them.
Get a starting point for tracking changes, list everything that has changed since, and open a notification channel for future changes.
List, read, create, update, and delete shared drives, and hide or unhide them from the default view.
Open a channel to watch a single file, and stop a channel to end notifications.
Read information about the user, their storage, and what the account's Drive supports.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Files & foldersList and search files, read a file's metadata or content, create and upload files, update, copy, and delete them, export Google Workspace documents, and empty the trash.10 | ||||||
| GET | /files | List and search the user's files and folders, filtered with a query string. | read | drive.readonly | Current | |
Listing across the account needs drive.readonly or drive. An app holding only drive.file sees just the files it created or the user picked. Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onfile Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit100 quota units SourceOfficial documentation ↗ | ||||||
| GET | /files/{fileId} | Get a file's metadata by ID, or its content with alt=media. | read | drive.file | Current | |
drive.file is enough for a file the app created or the user picked; reading any file in the account needs drive.readonly or drive. Full scope URL: https://www.googleapis.com/auth/drive.file Acts onfile Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units (metadata); 200 quota units (content download) SourceOfficial documentation ↗ | ||||||
| POST | /files | Create a new file or folder, optionally uploading content. | write | drive.file | Current | |
Uploading content uses the separate upload URI at https://www.googleapis.com/upload/drive/v3/files with uploadType set to media, multipart, or resumable. A file the app creates under drive.file stays accessible to that app. Full scope URL: https://www.googleapis.com/auth/drive.file Acts onfile Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| PATCH | /files/{fileId} | Update a file's metadata, content, or both. | write | drive.file | Current | |
Updating content uses the upload URI, like create. Full scope URL: https://www.googleapis.com/auth/drive.file Acts onfile Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| POST | /files/{fileId}/copy | Create a copy of a file, with optional metadata changes. | write | drive.file | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.file Acts onfile Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| DELETE | /files/{fileId} | Permanently delete a file the user owns, skipping the trash. | write | drive.file | Current | |
This bypasses the trash and cannot be undone. To trash instead, update the file with trashed set to true. Full scope URL: https://www.googleapis.com/auth/drive.file Acts onfile Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
| GET | /files/{fileId}/export | Export a Google Workspace document (Docs, Sheets, Slides) to a requested format such as PDF. | read | drive.readonly | Current | |
Only for Google-format documents; binary files use get with alt=media instead. The exported content is capped at 10 MB. Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onfile Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit200 quota units SourceOfficial documentation ↗ | ||||||
| GET | /files/generateIds | Generate a set of file IDs to use ahead of create or copy. | read | drive.file | Current | |
Pre-generating IDs lets an upload be retried safely without creating duplicates. Full scope URL: https://www.googleapis.com/auth/drive.file Acts onfile Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
| DELETE | /files/trash | Permanently delete all of the user's trashed files. | write | drive | Current | |
This empties the whole trash and cannot be undone, so it needs the full drive scope. Full scope URL: https://www.googleapis.com/auth/drive Acts onfile Permission (capability) driveVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
| POST | /files/{fileId}/watch | Open a notification channel to watch a single file for changes. | write | drive.file | Current | |
The channel posts to a webhook address and lasts at most 86,400 seconds (one day) for a file. Full scope URL: https://www.googleapis.com/auth/drive.file Acts onfile Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook event file-changeRate limit100 quota units SourceOfficial documentation ↗ | ||||||
Permissions (sharing)List who a file or shared drive is shared with, read a single permission, and grant, change, or revoke access.5 | ||||||
| GET | /files/{fileId}/permissions | List the permissions on a file or shared drive (who it is shared with). | read | drive.readonly | Current | |
Returns the people, groups, domains, and links a file is shared with. Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onpermission Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit100 quota units SourceOfficial documentation ↗ | ||||||
| GET | /files/{fileId}/permissions/{permissionId} | Get a single permission on a file by ID. | read | drive.readonly | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onpermission Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
| POST | /files/{fileId}/permissions | Grant access to a file or shared drive by creating a permission for a person, group, domain, or anyone with the link. | write | drive.file | Current | |
This is what shares a file with someone new; bulk sharing can hit the sharingRateLimitExceeded limit. Full scope URL: https://www.googleapis.com/auth/drive.file Acts onpermission Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit100 quota units SourceOfficial documentation ↗ | ||||||
| PATCH | /files/{fileId}/permissions/{permissionId} | Change an existing permission, for example from reader to writer. | write | drive.file | Current | |
An inherited permission on a shared drive item cannot be changed here. Full scope URL: https://www.googleapis.com/auth/drive.file Acts onpermission Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit100 quota units SourceOfficial documentation ↗ | ||||||
| DELETE | /files/{fileId}/permissions/{permissionId} | Revoke access by deleting a permission. | write | drive.file | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.file Acts onpermission Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit100 quota units SourceOfficial documentation ↗ | ||||||
Comments & repliesList, read, create, update, and delete comments on a file, and the replies threaded under them.8 | ||||||
| GET | /files/{fileId}/comments | List the comments on a file. | read | drive.readonly | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts oncomment Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit100 quota units SourceOfficial documentation ↗ | ||||||
| GET | /files/{fileId}/comments/{commentId} | Get a single comment by ID. | read | drive.readonly | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts oncomment Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
| POST | /files/{fileId}/comments | Create a comment on a file. | write | drive.file | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.file Acts oncomment Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| PATCH | /files/{fileId}/comments/{commentId} | Update a comment. | write | drive.file | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.file Acts oncomment Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| DELETE | /files/{fileId}/comments/{commentId} | Delete a comment. | write | drive.file | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.file Acts oncomment Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
| GET | /files/{fileId}/comments/{commentId}/replies | List the replies under a comment. | read | drive.readonly | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onreply Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit100 quota units SourceOfficial documentation ↗ | ||||||
| POST | /files/{fileId}/comments/{commentId}/replies | Create a reply to a comment. | write | drive.file | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.file Acts onreply Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| DELETE | /files/{fileId}/comments/{commentId}/replies/{replyId} | Delete a reply. | write | drive.file | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.file Acts onreply Permission (capability) drive.fileVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
ChangesGet a starting point for tracking changes, list everything that has changed since, and open a notification channel for future changes.3 | ||||||
| GET | /changes/startPageToken | Get the page token that marks the current point, to list changes from here on. | read | drive.readonly | Current | |
The returned token is the starting point for a later changes.list call. Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onchange Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
| GET | /changes | List the files that have changed for a user or shared drive since a page token. | read | drive.readonly | Current | |
Drives changes incrementally rather than re-scanning every file. Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onchange Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit100 quota units SourceOfficial documentation ↗ | ||||||
| POST | /changes/watch | Open a notification channel to watch all changes for a user. | write | drive.readonly | Current | |
The channel posts to a webhook address and lasts at most 604,800 seconds (one week) for changes. Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onchange Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook event account-changeRate limit100 quota units SourceOfficial documentation ↗ | ||||||
Shared drivesList, read, create, update, and delete shared drives, and hide or unhide them from the default view.7 | ||||||
| GET | /drives | List the shared drives the user can access. | read | drive.readonly | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onshared drive Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit100 quota units SourceOfficial documentation ↗ | ||||||
| GET | /drives/{driveId} | Get a shared drive's metadata by ID. | read | drive.readonly | Current | |
Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onshared drive Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
| POST | /drives | Create a new shared drive. | write | drive | Current | |
Working with shared drives needs the full drive scope. Full scope URL: https://www.googleapis.com/auth/drive Acts onshared drive Permission (capability) driveVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| PATCH | /drives/{driveId} | Update a shared drive's metadata. | write | drive | Current | |
Full scope URL: https://www.googleapis.com/auth/drive Acts onshared drive Permission (capability) driveVersionAvailable since the API’s base version Webhook eventNone Rate limit50 quota units SourceOfficial documentation ↗ | ||||||
| DELETE | /drives/{driveId} | Permanently delete a shared drive the user organizes. | write | drive | Current | |
The shared drive must have no files unless allowItemDeletion is set. Full scope URL: https://www.googleapis.com/auth/drive Acts onshared drive Permission (capability) driveVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
| POST | /drives/{driveId}/hide | Hide a shared drive from the default view. | write | drive | Current | |
Full scope URL: https://www.googleapis.com/auth/drive Acts onshared drive Permission (capability) driveVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
| POST | /drives/{driveId}/unhide | Restore a shared drive to the default view. | write | drive | Current | |
Full scope URL: https://www.googleapis.com/auth/drive Acts onshared drive Permission (capability) driveVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
NotificationsOpen a channel to watch a single file, and stop a channel to end notifications.1 | ||||||
| POST | /channels/stop | Stop a notification channel so it sends no more notifications. | write | drive.readonly | Current | |
Takes the channel id and resourceId returned when the channel was opened; only the creator can stop it. Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onchannel Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
AboutRead information about the user, their storage, and what the account's Drive supports.1 | ||||||
| GET | /about | Read information about the user, their storage quota, and what the account's Drive supports. | read | drive.readonly | Current | |
The fields parameter is required on this method. Full scope URL: https://www.googleapis.com/auth/drive.readonly Acts onabout Permission (capability) drive.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limit5 quota units SourceOfficial documentation ↗ | ||||||
Google Drive can notify an app or AI agent when something changes, instead of the app repeatedly asking. An app opens a notification channel on a file or on the whole account, and Drive sends a request to the channel's webhook address each time the watched thing changes.
| Event | What it signals | Triggered by |
|---|---|---|
File change notification | Sent to the channel's webhook address when a watched file changes. The X-Goog-Resource-State header names the change, such as update, trash, untrash, or remove, and sync confirms the channel opened. | /files/{fileId}/watch |
Changes notification | Sent to the channel's webhook address when anything in the watched user's Drive changes. The receiver then calls changes.list with its page token to fetch what changed. The X-Goog-Resource-State header carries the change state. | /changes/watch |
Google Drive limits how much an app or AI agent can call, by metering each call in quota units against a per-project and a per-user budget that refill every minute.
Google Drive meters each call in quota units against a budget that refills every minute, rather than counting raw requests. A project gets 1,000,000 quota units per minute, and a single user within that project gets 325,000 quota units per minute, so one heavy user cannot exhaust the whole project. Calls cost different amounts: a read is 5 units, an edit is 50, a list is 100, and a content download is 200, so a project could make roughly 10,000 list calls a minute before the per-project budget runs out. Going over returns a 403 with reason userRateLimitExceeded or rateLimitExceeded, or a 429, and the fix is exponential backoff with jitter rather than immediate retries. Bulk sharing has its own ceiling, surfaced as sharingRateLimitExceeded.
List methods page through results with pageSize, which sets how many items come back per page, and a nextPageToken in each response that is passed as pageToken to fetch the following page until no token is returned. The fields parameter should be set to request only the fields an integration needs, which keeps responses small and the quota cost down. Changes are paged differently: changes.list walks forward from a page token, and getStartPageToken provides the starting point.
Requests and responses are JSON. File content is uploaded and downloaded through a separate media URI, where simple and multipart uploads are for content of 5 MB or less and resumable uploads handle larger content. Exporting a Google Workspace document with files.export returns at most 10 MB; larger documents must be fetched another way.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | badRequest | A required parameter is missing or a value is invalid, for example a malformed query in files.list. | Read the message field, correct the parameters, and resend. The request is not retryable as-is. |
| 401 | authError | Invalid credentials: the access token is missing, expired, or invalid. | Refresh the access token, or send the user back through the OAuth consent flow, then retry. |
| 403 | userRateLimitExceeded / rateLimitExceeded | A per-user or per-project rate limit was exceeded. The body's reason field names which limit was hit. | Retry with exponential backoff and jitter, smooth the request rate, and request more quota if the project consistently needs it. |
| 403 | insufficientFilePermissions | The user does not have sufficient permission for the file, for example trying to write to a file shared read-only. | Ask the file owner for edit access, or fall back to a read-only path. This is not fixed by retrying. |
| 403 | appNotAuthorizedToFile / domainPolicy | The app lacks access to this file under the drive.file scope, or a Workspace administrator has disabled Drive apps for the domain. | Have the user open the file through a file picker so the app gains access, or contact the domain administrator to allow the app. |
| 403 | sharingRateLimitExceeded | Too many sharing changes were made too quickly, often during bulk sharing that sends notification emails. | Slow the rate of sharing changes, skip notification emails on bulk shares, or use a service account with domain-wide delegation. |
| 404 | notFound | The file does not exist, or the token cannot see it. Drive returns 404 rather than 403 so it does not reveal a file the user cannot access. | Confirm the file ID, set supportsAllDrives=true for shared-drive files, and confirm the token has access to the file. |
| 429 | rateLimitExceeded | Too many requests were sent in a short window, hitting the per-minute quota-unit budget. | Back off exponentially with jitter before retrying, and spread requests out over time. |
| 500 | backendError | An unexpected error on Google's side, which can also appear as 502, 503, or 504. | Retry the request with exponential backoff. If it persists, check the Google Workspace Status Dashboard. |
Google Drive's API is on version 3, a single REST version that gains features through dated release notes rather than new version numbers.
Version 3 is the current Google Drive REST API, reached at the /drive/v3 path. There are no dated API versions; features, deprecations, and new resources ship through the release notes. Recent notable changes are listed below, newest first.
Selected dated changes from 2025, newest first.
An integration builds against v3 and tracks the release notes for new resources and deprecations.
Google Drive API release notes ↗Bollard AI sits between a team's AI agents and Google Drive. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.