google-drive

# Google Drive Access the Google Drive API with managed OAuth authentication. List, search, create, and manage files and folders. ## Quick Start ```bash # List files python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-drive/drive/v3/files?pageSize=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/google-drive/{native-api-path} ``` Replace `{native-api-path}` with the actual Google Drive API endpoint path. The gateway proxies requests to `www.googleapis.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Google OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-drive&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'google-drive'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "google-drive", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Google Drive connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-drive/drive/v3/files?pageSize=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### List Files ```bash GET /google-drive/drive/v3/files?pageSize=10 ``` With query: ```bash GET /google-drive/drive/v3/files?q=name%20contains%20'report'&pageSize=10 ``` Only folders: ```bash GET /google-drive/drive/v3/files?q=mimeType='application/vnd.google-apps.folder' ``` Files in specific folder: ```bash GET /google-drive/drive/v3/files?q='FOLDER_ID'+in+parents ``` With fields: ```bash GET /google-drive/drive/v3/files?fields=files(id,name,mimeType,createdTime,modifiedTime,size) ``` ### Get File Metadata ```bash GET /google-drive/drive/v3/files/{fileId}?fields=id,name,mimeType,size,createdTime ``` ### Download File Content ```bash GET /google-drive/drive/v3/files/{fileId}?alt=media ``` ### Export Google Docs ```bash GET /google-drive/drive/v3/files/{fileId}/export?mimeType=application/pdf ``` ### Create File (metadata only) ```bash POST /google-drive/drive/v3/files Content-Type: application/json { "name": "New Document", "mimeType": "application/vnd.google-apps.document" } ``` ### Create Folder ```bash POST /google-drive/drive/v3/files Content-Type: application/json { "name": "New Folder", "mimeType": "application/vnd.google-apps.folder" } ``` ### Update File Metadata ```bash PATCH /google-drive/drive/v3/files/{fileId} Content-Type: application/json { "name": "Renamed File" } ``` ### Move File to Folder ```bash PATCH /google-drive/drive/v3/files/{fileId}?addParents=NEW_FOLDER_ID&removeParents=OLD_FOLDER_ID ``` ### Delete File ```bash DELETE /google-drive/drive/v3/files/{fileId} ``` ### Copy File ```bash POST /google-drive/drive/v3/files/{fileId}/copy Content-Type: application/json { "name": "Copy of File" } ``` ## File Uploads Google Drive supports three upload types depending on file size and whether you need to include metadata. ### Simple Upload (Media) For files up to 5MB when you don't need to set metadata. ```bash POST /google-drive/upload/drive/v3/files?uploadType=media Content-Type: text/plain <file content> ``` **Python Example:** ```python import urllib.request, os file_content = b"Hello, this is file content!" url = "https://gateway.maton.ai/google-drive/upload/drive/v3/files?uploadType=media" req = urllib.request.Request(url, data=file_content, method="POST") req.add_header("Authorization", f"Bearer {os.environ['MATON_API_KEY']}") req.add_header("Content-Type", "text/plain") response = urllib.request.urlopen(req) ``` ### Multipart Upload For files up to 5MB when you need to include metadata (name, description, etc.). ```bash POST /google-drive/upload/drive/v3/files?uploadType=multipart Content-Type: multipart/related; boundary=boundary --boundary Content-Type: application/json; charset=UTF-8 {"name": "myfile.txt", "description": "My file"} --boundary Content-Type: text/plain <file content> --boundary-- ``` **Python Example:** ```python import urllib.request, os, json boundary = "----Boundary" metadata = json.dumps({"name": "myfile.txt", "description": "My file"}) file_content = "File content here" body = f"""--{boundary}\r Content-Type: application/json; charset=UTF-8\r \r {metadata}\r --{boundary}\r Content-Type: text/plain\r \r {file_content}\r --{boundary}--""".encode() url = "https://gateway.maton.ai/google-drive/upload/drive/v3/files?uploadType=multipart" req = urllib.request.Request(url, data=body, method="POST") req.add_header("Authorization", f"Bearer {os.environ['MATON_API_KEY']}") req.add_header("Content-Type", f"multipart/related; boundary={boundary}") response = urllib.request.urlopen(req) ``` ### Resumable Upload (Large Files) For large files (recommended for files > 5MB). This approach: 1. Initiates a session - Gets an upload URI 2. Uploads in chunks - Sends file in pieces 3. Supports resume - Can continue from where it left off if interrupted **Step 1: Initiate Upload Session** ```bash POST /google-drive/upload/drive/v3/files?uploadType=resumable Content-Type: application/json; charset=UTF-8 X-Upload-Content-Type: application/octet-stream X-Upload-Content-Length: <file_size> {"name": "large_file.bin"} ``` Response includes `Location` header with the upload URI. **Step 2: Upload Content** ```bash PUT <upload_uri> Content-Length: <file_size> Content-Type: application/octet-stream <file content> ``` **Python Example (Complete):** ```python import urllib.request, os, json file_path = "/path/to/large_file.bin" file_size = os.path.getsize(file_path) # Step 1: Initiate resumable upload session url = "https://gateway.maton.ai/google-drive/upload/drive/v3/files?uploadType=resumable" metadata = json.dumps({"name": "large_file.bin"}).encode() req = urllib.request.Request(url, data=metadata, method="POST") req.add_header("Authorization", f"Bearer {os.environ['MATON_API_KEY']}") req.add_header("Content-Type", "application/json; charset=UTF-8") req.add_header("X-Upload-Content-Type", "application/octet-stream") req.add_header("X-Upload-Content-Length", str(file_size)) response = urllib.request.urlopen(req) upload_uri = response.headers["Location"] # Step 2: Upload file in chunks (e.g., 5MB chunks) chunk_size = 5 * 1024 * 1024 with open(file_path, "rb") as f: offset = 0 while offset < file_size: chunk = f.read(chunk_size) end = offset + len(chunk) - 1 req = urllib.request.Request(upload_uri, data=chunk, method="PUT") req.add_header("Content-Length", str(len(chunk))) req.add_header("Content-Range", f"bytes {offset}-{end}/{file_size}") response = urllib.request.urlopen(req) offset += len(chunk)