Google Drive organizes resources primarily around files and shared drives. Files are the central entity: most actions (metadata read/write, content download/upload, comments, permissions, revisions) require a fileId. Shared drives (current API surface under drives.*) are identified by driveId (older teamDriveId parameters are present but deprecated). Permissions, comments, replies and revisions are always scoped to a particular fileId and then by permissionId, commentId, replyId, or revisionId as appropriate.

Key entities and relationships

• Files: the primary resource. Use fileId to read metadata (files.get), download content (files.get with alt=media or files.download / files.export), create (files.create), copy (files.copy), update (files.update), and manipulate parents (addParents/removeParents). Folder objects are files with mimeType = application/vnd.google-apps.folder.

• Permissions: attached to files or shared drives. Typical flow is permissions.list → inspect → permissions.create / permissions.update / permissions.delete to change sharing.

• Comments and replies: always under a fileId. Use comments.* and replies.* endpoints to create, list, update, and delete discussion threads on a file.

• Revisions: per-file version history. Use revisions.list/get/update/delete. The keepForever (pinned) limit is product-level (see gotchas).

• Shared drives: managed with drives.*. Use drives.list to discover driveIds; many file operations accept a driveId or require supportsAllDrives when operating across My Drive and shared drives.

• Changes and Operations: change-tracking uses changes.getStartPageToken → changes.list (supply the returned pageToken). Watch endpoints produce push notifications (channels) and some content/downloads can surface as long-running Operation resources that you can poll via operations.get.

First calls (entry points)

• Discover what belongs to the user or a shared drive:

  • drive.files.list with a q filter or driveId to find files and obtain fileIds.
  • drive.drives.list to find shared drives (driveId).

• For change tracking: call drive.changes.getStartPageToken to obtain a pageToken to start listing changes.

• To prepare IDs before creation (shortcuts or pre-declared files): drive.files.generateIds returns ready-to-use IDs.

• Get account-level info (user, storage limits): drive.about.get.

Start with files.list or drives.list when users ask for file discovery, and with about.get for account context.

Common user tasks and the minimal sequences to achieve them

Each sequence lists the operations you will call and the key parameters to provide (do not repeat obvious type details shown in operation signatures).

1. Find a file or folder by name or other metadata

• Call drive.files.list with a q query (e.g. name = 'Report.docx' and trashed = false) and optional driveId/corpora/spaces depending on scope. Use pageToken when results paginate.

2. Read file metadata and content

• Get metadata: drive.files.get with fileId.
• If the file is a Google Workspace doc (Docs/Sheets/Slides), export its content in a chosen format with drive.files.export and the mimeType to receive the converted content.
• For binary/non-native files or to download a specific revision, use files.get/files.download with alt=media or a revisionId. Note: some download flows return an Operation resource; check the response and, if you receive an Operation, poll operations.get using the returned operation name.

3. Upload a new file or create a folder

• Create folder: drive.files.create with body containing name and mimeType: application/vnd.google-apps.folder and optional parents to place it.
• Upload file content: drive.files.create with file metadata in the body. Provide parents to put the file into a folder. To place files in shared drives, include supportsAllDrives=true and/or driveId as needed.

4. Copy a file (create a new file from an existing one)

• drive.files.copy with the source fileId and optional body to set a new name or parents.
• Note: copying files into multiple parents is deprecated—use shortcuts if you need a file to appear in multiple places.

5. Share a file or change access

• Inspect current access: drive.permissions.list with fileId.
• Grant access: drive.permissions.create with fileId and a permission body (type: user/group/domain/anyone, role: reader/writer/owner, and emailAddress when appropriate). To transfer ownership, set transferOwnership=true and confirm with role: 'owner'.
• Adjust notification: sendNotificationEmail defaults to true for user/group shares; ownership transfers require notifications and cannot disable them.

6. Work with comments and replies

• Create a comment: drive.comments.create with fileId and comment body.
• List comments: drive.comments.list (filter with startModifiedTime if needed).
• Create a reply: drive.replies.create with fileId and commentId.
• Deleted comments/replies are returned only when includeDeleted=true.

7. Manage revisions

• List revisions: drive.revisions.list with fileId.
• Pin a revision (keepForever): drive.revisions.update and set keepForever=true. There is a platform limit on the number of revisions that can be pinned (200); if the limit is reached, older pins must be removed before pinning new revisions.

8. Track changes and receive notifications

• Start: drive.changes.getStartPageToken to obtain the token to feed into drive.changes.list.
• Poll or page through drive.changes.list using the token; include includeItemsFromAllDrives, driveId, and restrictToMyDrive according to scope.
• For push notifications, call drive.changes.watch (supply a channel body). To stop a channel, call drive.channels.stop.

9. Handle shared drive lifecycle

• Create a shared drive: drive.drives.create with a client-supplied requestId to make creation idempotent (a repeated request with the same requestId will not create duplicates; if the drive already exists, expect a 409).
• Delete a shared drive: drive.drives.delete—if you need to delete items inside the drive, useDomainAdminAccess=true and allowItemDeletion=true are required (domain admin scenarios).

Long-running / asynchronous results

Some endpoints return or surface long-running Operation resources (for example certain downloads or other background tasks). When an operation resource appears in a response, use the operation's name with drive.operations.get to observe completion and retrieve results. The presence of an Operation in a response indicates the task is asynchronous—check done and the operation payload.

Frequent parameters and their effects (patterns rather than full lists)

• fileId: required for almost all file-scoped actions; obtain it from files.list or search results.
• driveId vs teamDriveId: use driveId for shared drives; teamDriveId is deprecated in favor of driveId.
• supportsAllDrives: set to true when working across My Drive and shared drives (list/get/copy/update operations often need this when files may live in shared drives).
• useDomainAdminAccess: required for domain-administrator privileged operations on shared drives and permissions; this can grant access for administrative tasks.
• pageToken/pageSize: present on list endpoints—use pageToken from prior responses to continue listing.
• includePermissionsForView: only published is supported; include only when you specifically need that view.

Non-obvious gotchas and practical tips

• Google Workspace native files (Docs/Sheets/Slides) must be exported via drive.files.export to get payloads in common formats (PDF, DOCX, XLSX, etc.). Using files.get/alt=media will not convert native docs—use export for conversions.

• files.download in this surface can return an Operation (async). If the response is an Operation, poll drive.operations.get with the returned operation name. Always inspect the response body type to determine whether content is returned directly or via an operation.

• Copying into multiple parents is deprecated. If users want a file to appear in multiple folders, create a shortcut instead.

• When transferring file ownership: set transferOwnership=true on the permissions.create or permissions.update call. Ownership transfers may move the item to the new owner’s root when moveToNewOwnersRoot=true is set (only applies outside shared drives). Notifications for ownership transfers cannot be suppressed.

• Shared drive creation is idempotent when you provide a requestId. Repeating the same requestId will not create duplicates; if a drive with the same identity exists, expect a 409 conflict.

• Deleting a shared drive’s contents requires admin privileges: useDomainAdminAccess=true plus allowItemDeletion=true on drives.delete to remove items inside in domain-admin scenarios.

• supportsTeamDrives and teamDriveId parameters are deprecated—prefer supportsAllDrives and driveId.

• Revisions pinned with keepForever=true are limited (200 pinned revisions per file). If a pin fails due to quota, unpin older revisions first via revisions.update.

• Label-related operations (files.listLabels, files.modifyLabels) return and accept label data separate from file metadata. Include includeLabels in calls that can return labelInfo when you expect label details.

• Permissions API behavior varies by scope: useDomainAdminAccess can grant domain-level privileges for admin flows, and enforceExpansiveAccess exists to control enforcement semantics. When in doubt, list permissions first (permissions.list) to see current state before applying changes.

When a user asks something typical, what to call first

• “Show me my recent files”: call drive.files.list ordered by modifiedTime or recency with the appropriate q filter.
• “Download X document as PDF”: find fileId via files.list, then call drive.files.export with mimeType=application/pdf.
• “Share this file with alice@example.com as editor”: drive.permissions.create with fileId and permission body (type: 'user', emailAddress: 'alice@example.com', role: 'writer'), set sendNotificationEmail as desired; include transferOwnership=true only if making owner.
• “Watch for changes in my Drive”: call drive.changes.getStartPageToken then drive.changes.list with the returned token; use drive.changes.watch if push notifications are preferred.

Focus on obtaining fileId and driveId early—most errors come from operating on the wrong scope (My Drive vs shared drive) or failing to set supportsAllDrives / useDomainAdminAccess when needed. Use files.list and drives.list to discover IDs and then follow the small, task-specific sequences above to complete user requests.