Google Docs
Access the Google Docs API with managed OAuth authentication. Create documents, insert and format text, and manage document content.
Quick Start
# Get document
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-docs/v1/documents/{documentId}')
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-docs/{native-api-path}
Replace
{native-api-path}
with the actual Google Docs API endpoint path. The gateway proxies requests to
docs.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
:
export MATON_API_KEY="YOUR_API_KEY"
Getting Your API Key
- Sign in or create an account at maton.ai
- Go to maton.ai/settings
- Copy your API key
Connection Management
Manage your Google OAuth connections at
https://ctrl.maton.ai
.
List Connections
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-docs&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
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-docs'}).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
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:
{
"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-docs",
"metadata": {}
}
}
Open the returned
url
in a browser to complete OAuth authorization.
Delete Connection
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 Docs connections, specify which one to use with the
Maton-Connection
header:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-docs/v1/documents/{documentId}')
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
Get Document
GET /google-docs/v1/documents/{documentId}
Create Document
POST /google-docs/v1/documents
Content-Type: application/json
{
"title": "New Document"
}
Batch Update Document
POST /google-docs/v1/documents/{documentId}:batchUpdate
Content-Type: application/json
{
"requests": [
{
"insertText": {
"location": {"index": 1},
"text": "Hello, World!"
}
}
]
}
Common batchUpdate Requests
Insert Text
{
"insertText": {
"location": {"index": 1},
"text": "Text to insert"
}
}
Delete Content
{
"deleteContentRange": {
"range": {
"startIndex": 1,
"endIndex": 10
}
}
}
Replace All Text
{
"replaceAllText": {
"containsText": {
"text": "{{placeholder}}",
"matchCase": true
},
"replaceText": "replacement value"
}
}
Insert Table
{
"insertTable": {
"location": {"index": 1},
"rows": 3,
"columns": 3
}
}
Update Text Style
{
"updateTextStyle": {
"range": {
"startIndex": 1,
"endIndex": 10
},
"textStyle": {
"bold": true,
"fontSize": {"magnitude": 14, "unit": "PT"}
},
"fields": "bold,fontSize"
}
}
Insert Page Break
{
"insertPageBreak": {
"location": {"index": 1}
}
}
Code Examples
JavaScript
// Create document
const response = await fetch(
'https://gateway.maton.ai/google-docs/v1/documents',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.MATON_API_KEY}`
},
body: JSON.stringify({ title: 'New Document' })
}
);
// Insert text
await fetch(
https://gateway.maton.ai/google-docs/v1/documents/${docId}:batchUpdate
,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': Bearer ${process.env.MATON_API_KEY}
},
body: JSON.stringify({
requests: [{ insertText: { location: { index: 1 }, text: 'Hello!' } }]
})
}
);
Python
import os
import requests
Create document
response = requests.post(
'https://gateway.maton.ai/google-docs/v1/documents',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
json={'title': 'New Document'}
)
Notes
- Index positions are 1-based (document starts at index 1)
- Use
endOfSegmentLocation
to append at end
- Multiple requests in batchUpdate are applied atomically
- Get document first to find correct indices for updates
- The
fields
parameter in style updates uses field mask syntax
- 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 Docs connection |
| 401 | Invalid or missing Maton API key |
| 429 | Rate limited (10 req/sec per account) |
| 4xx/5xx | Passthrough error from Google Docs API |
Troubleshooting: API Key Issues
- Check that the
MATON_API_KEY
environment variable is set:
echo $MATON_API_KEY
- Verify the API key is valid by listing connections:
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
- Ensure your URL path starts with
google-docs
. For example:
- Correct:
https://gateway.maton.ai/google-docs/v1/documents/{documentId}
- Incorrect:
https://gateway.maton.ai/docs/v1/documents/{documentId}
Resources
