Introduction
# 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)
result = json.load(response) print(f"Uploaded: {result['id']}") ```
**Resuming Interrupted Uploads:**
If an upload is interrupted, query the upload URI to get current status:
```python req = urllib.request.Request(upload_uri, method='PUT') req.add_header('Content-Length', '0') req.add_header('Content-Range', 'bytes */*') response = urllib.request.urlopen(req) # Check Range header in response to get current offset ```
### Update File Content
To update an existing file's content:
```bash PATCH /google-drive/upload/drive/v3/files/{fileId}?uploadType=media Content-Type: text/plain
<new file content> ```
**Python Example:** ```python import urllib.request, os
file_id = 'YOUR_FILE_ID' new_content = b'Updated file content!'
url = f'https://gateway.maton.ai/google-drive/upload/drive/v3/files/{file_id}?uploadType=media' req = urllib.request.Request(url, data=new_content, method='PATCH') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'text/plain') response = urllib.request.urlopen(req) ```
### Upload to Specific Folder
Include the folder ID in the metadata:
```python metadata = json.dumps({ 'name': 'myfile.txt', 'parents': ['FOLDER_ID'] }) ```
### Share File
```bash POST /google-drive/drive/v3/files/{fileId}/permissions Content-Type: application/json
{ "role": "reader", "type": "user", "emailAddress": "[email protected]" } ```
## Query Operators
Use in the `q` parameter: - `name = 'exact name'` - `name contains 'partial'` - `mimeType = 'application/pdf'` - `'folderId' in parents` - `trashed = false` - `modifiedTime > '2024-01-01T00:00:00'`
Combine with `and`: ``` name contains 'report' and mimeType = 'application/pdf' ```
## Common MIME Types
- `application/vnd.google-apps.document` - Google Docs - `application/vnd.google-apps.spreadsheet` - Google Sheets - `application/vnd.google-apps.presentation` - Google Slides - `application/vnd.google-apps.folder` - Folder - `application/pdf` - PDF
## Code Examples
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/google-drive/drive/v3/files?pageSize=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/google-drive/drive/v3/files', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'pageSize': 10} ) ```
## Notes
- Use `fields` parameter to limit response data - Pagination uses `pageToken` from previous response's `nextPageToken` - Export is for Google Workspace files only - **Upload Types**: Use `uploadType=media` for simple uploads (up to 5MB), `uploadType=multipart` for uploads with metadata (up to 5MB), `uploadType=resumable` for large files (recommended for > 5MB) - **Upload Endpoint**: File uploads use `/upload/drive/v3/files` (note the `/upload` prefix) - **Resumable Uploads**: For large files, use resumable uploads with chunked transfer (256KB minimum chunk size, 5MB recommended) - **Max File Size**: Google Drive supports files up to 5TB - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.
## Error Handling
| Status | Meaning | |--------|---------| | 400 | Missing Google Drive connection | | 401 | Invalid or missing Maton API key | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from Google Drive API |
### Troubleshooting: API Key Issues
1. Check that the `MATON_API_KEY` environment variable is set:
```bash echo $MATON_API_KEY ```
2. Verify the API key is valid by listing connections:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Troubleshooting: Invalid App Name
1. Ensure your URL path starts with `google-drive`. For example:
- Correct: `https://gateway.maton.ai/google-drive/drive/v3/files` - Incorrect: `https://gateway.maton.ai/drive/v3/files`
## Resources
- [Drive API Overview](https://developers.google.com/drive/api/reference/rest/v3) - [List Files](https://developers.google.com/drive/api/reference/rest/v3/files/list) - [Get File](https://developers.google.com/drive/api/reference/rest/v3/files/get) - [Create File](https://developers.google.com/drive/api/reference/rest/v3/files/create) - [Update File](https://developers.google.com/drive/api/reference/rest/v3/files/update) - [Delete File](https://developers.google.com/drive/api/reference/rest/v3/files/delete) - [Export File](https://developers.google.com/drive/api/reference/rest/v3/files/export) - [Upload Files](https://developers.google.com/drive/api/guides/manage-uploads) - [Resumable Uploads](https://developers.google.com/drive/api/guides/manage-uploads#resumable) - [Search Query Syntax](https://developers.google.com/drive/api/guides/search-files) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])