Google Drive

Google Drive Integration

Drive Adapter Architecture

GoogleDriveService → GoogleDriveAdapter → Google Drive API v3

Service Layer

GoogleDriveService

service.py
@service_method
15 methods

calls

→

Adapter

GoogleDriveAdapter

adapter.py
httpx + OAuth token
MIME-type routing

REST v3

→

External API

Google Drive API

v3 · drive.googleapis.com
files · permissions

OAuth 2.0 Scope Tiers

Read-Only

drive.readonly

drive.metadata.readonly

list · search · metadata · download

Full Access

drive.file

drive

create · copy · share · delete

What & Why

Google Drive integration exposes file management and document content access through the Google Drive REST API v3, with special handling for Google Workspace native formats (Docs, Sheets, Slides) that must be exported rather than downloaded directly.

Key use cases:

GraphRAG ingestion — read Google Docs, Sheets, and Slides as DOCX/XLSX/PDF for document chunking and embedding
File search — find files by name, type, or full-text query across a user's Drive
Template workflows — copy template files and populate new Drive documents programmatically
Programmatic sharing — grant access to files or folders for specific users or domains
Content access — read file content directly for processing without storing locally

The adapter automatically detects Google Workspace MIME types and routes requests through the export endpoint instead of the binary download endpoint. Regular files (PDF, DOCX, images) are downloaded directly.

Google Workspace Export Formats

MIME-type routing: export vs direct download

📄 Google Doc

application/vnd.google-apps.document

→ export →

DOCXPDFTXTHTML

📊 Google Sheet

application/vnd.google-apps.spreadsheet

→ export →

XLSXCSVPDF

🎞 Google Slide

application/vnd.google-apps.presentation

→ export →

PPTXPDF

📎 Regular Files

PDF · DOCX · PNG · MP4 · …

→ direct download →

binary streamno conversion

The adapter checks mimeType on every file response. Google Workspace types route to /files/{id}/export; all others to /files/{id}?alt=media.

Methods Reference

Method	Description	Key Parameters
`list_recent_files`	List files recently modified or accessed in Drive	`page_size`, `order_by`, `fields`
`search_files`	Search files by name, content, type, or custom Drive query	`query` (Drive query string), `page_size`, `fields`
`get_file_metadata`	Retrieve metadata for a specific file by ID	`file_id`, `fields`
`get_file_permissions`	List all permissions (users, groups, domains) on a file	`file_id`
`download_file_content`	Download raw binary content of a file; exports Workspace formats	`file_id`, `export_mime_type`
`read_file_content`	Read file content as decoded text; auto-exports Workspace formats	`file_id`, `export_mime_type`
`create_file`	Create a new file or folder in Drive	`name`, `mime_type`, `content`, `folder_id`
`copy_file`	Copy an existing file to a new location	`file_id`, `name`, `folder_id`
`update_permissions`	Share a file with a user or domain by adding/updating a permission	`file_id`, `role`, `type`, `email_address`, `domain`
`list_files_in_folder`	List all files inside a specific folder	`folder_id`, `page_size`, `fields`
`move_file`	Move a file to a different parent folder	`file_id`, `folder_id`
`delete_file`	Permanently delete a file or folder	`file_id`
`update_file_content`	Update the content of an existing file	`file_id`, `content`, `mime_type`
`get_file_revisions`	List revision history for a file	`file_id`
`create_folder`	Create a new folder (shorthand: `create_file` with Workspace folder MIME type)	`name`, `parent_folder_id`

Google Workspace MIME types

To create a Google Drive folder programmatically, use create_file with mime_type=application/vnd.google-apps.folder. No content body is needed.

Scope requirements

list_recent_files, search_files, get_file_metadata, get_file_permissions, read_file_content, and download_file_content work with the read-only scope (drive.readonly or drive.metadata.readonly).

create_file, copy_file, update_permissions, move_file, delete_file, update_file_content, and create_folder require the full access scope (drive.file or drive).

CLI Examples

Search and read files

# Search files by name
constellation google-drive search-files --query "name contains 'Q1 Report'"

# Search by MIME type (all Google Docs)
constellation google-drive search-files --query "mimeType='application/vnd.google-apps.document'"

# Search for files modified in the last 7 days
constellation google-drive search-files --query "modifiedTime > '2026-05-05T00:00:00'"

# List recently modified files (last 20)
constellation google-drive list-recent-files --page-size 20

# Get file metadata
constellation google-drive get-file-metadata --file-id 1abc123XYZ

# Read file content (auto-exports Google Docs to plain text)
constellation google-drive read-file-content --file-id 1abc123XYZ

# Read a Google Sheet exported as CSV
constellation google-drive read-file-content --file-id 1abc123XYZ --export-mime-type text/csv

# Download a Google Slide deck as PDF
constellation google-drive download-file-content --file-id 1abc123XYZ --export-mime-type application/pdf

Create and manage files

# Create a Markdown file in a specific folder
constellation google-drive create-file \
  --name "report.md" \
  --content "# Q1 Report\n\nContent here." \
  --folder-id 1xyz789ABC

# Create a new folder
constellation google-drive create-folder \
  --name "Project Archive" \
  --parent-folder-id 1xyz789ABC

# Copy a template file
constellation google-drive copy-file \
  --file-id 1template123 \
  --name "2026-Q2-Report-Copy" \
  --folder-id 1xyz789ABC

# Move a file to a different folder
constellation google-drive move-file --file-id 1abc123XYZ --folder-id 1newFolder456

# Delete a file
constellation google-drive delete-file --file-id 1abc123XYZ

# Share a file with a specific user (editor)
constellation google-drive update-permissions \
  --file-id 1abc123XYZ \
  --role writer \
  --type user \
  --email-address colleague@example.com

# Share a file with an entire domain (viewer)
constellation google-drive update-permissions \
  --file-id 1abc123XYZ \
  --role reader \
  --type domain \
  --domain example.com

# List current permissions on a file
constellation google-drive get-file-permissions --file-id 1abc123XYZ

HTTP API

# Search files via HTTP
curl -X POST https://api.yourdomain.com/google-drive/search-files \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "name contains '\''Q1 Report'\''", "page_size": 10}'

# Response
# {
#   "files": [
#     {"id": "1abc123XYZ", "name": "Q1 Report.docx", "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "modifiedTime": "2026-05-01T10:00:00Z"}
#   ],
#   "nextPageToken": null
# }

# Read file content via HTTP
curl -X POST https://api.yourdomain.com/google-drive/read-file-content \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "1abc123XYZ"}'

# Create a file via HTTP
curl -X POST https://api.yourdomain.com/google-drive/create-file \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "report.md",
    "content": "# Report",
    "folder_id": "1xyz789ABC"
  }'

# Response
# {
#   "id": "1newFile789",
#   "name": "report.md",
#   "mimeType": "text/markdown",
#   "createdTime": "2026-05-12T14:00:00Z"
# }

Auth Setup

The Google Drive adapter uses OAuth 2.0 with Google's authorization server.

# Initiate OAuth flow
POST /v1/oauth/google-drive/authorize
# → { "authorization_url": "https://accounts.google.com/o/oauth2/auth?..." }

# Check authorization status
GET /v1/oauth/google-drive/status
# → { "status": "authorized", "user_email": "user@gmail.com" }

# Revoke tokens
DELETE /v1/oauth/google-drive/revoke

Environment variables:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://localhost:4002/oauth/google/callback

Drive Adapter Architecture

What & Why​

MIME-type routing: export vs direct download

Methods Reference​

CLI Examples​

Search and read files​

Create and manage files​

Permissions and sharing​

HTTP API​

Auth Setup​

What & Why

Methods Reference

CLI Examples

Search and read files

Create and manage files

Permissions and sharing

HTTP API

Auth Setup