Fize/workspace-kit

Google Docs (Cloud Document Skill)

Access the Google Docs API with managed OAuth authentication via Maton. Create, read, update, format, and batch-edit Google Docs cloud documents.

⚠️ Cloud vs. Local File Scope Distinction:

• google-docs (This Skill): Exclusively for online Google Docs cloud documents (docs.google.com/document/d/{documentId}). Interacts directly with Google's cloud servers via Maton OAuth API proxy.
• docx Skill: For reading, creating, or editing local .docx / .doc files stored on the local disk.

---

Quick Start

CLI:

# Get Document structure & text content
maton google-docs document get <documentId>

# Create a new Google Doc
maton google-docs document create --title 'Project Architecture Spec'

# Append text to a document body
maton google-docs document write <documentId> --text 'Meeting notes: discussion on Q3 roadmap.'

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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://api.maton.ai/google-docs/{native-api-path}

Maton proxies requests to docs.googleapis.com and automatically injects your OAuth token.

---

CLI Installation (optional — agent decides)

Maton CLI is optional. Agent can decide whether to install it based on the environment.

macOS / Linux

curl -fsSL https://maton.ai/install.sh | bash

Windows

irm https://maton.ai/install.ps1 | iex

npm (cross-platform)

npm install -g @maton/cli

Homebrew (macOS)

brew install maton-ai/cli/maton

After installation, verify with:

maton --version

---

Authentication

CLI:

maton login                          # Opens browser for API key
maton login --interactive            # Skip browser, paste API key directly
maton whoami                         # Show current auth state

Manual:

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key
4. Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

---

Connection Management

Manage your Google Docs OAuth connections at https://api.maton.ai.

List Connections

CLI:

maton connection list google-docs --status ACTIVE

maton api -X GET /connections -f app=google-docs -f status=ACTIVE

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

CLI:

maton connection create google-docs

maton api /connections -f app=google-docs

Python:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-docs'}).encode()
req = urllib.request.Request('https://api.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

Response:

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-docs"
  }
}

Open the returned url in a browser to complete OAuth authorization.

Get Connection

CLI:

maton connection get {connection_id}                 # alias: maton connection view

maton api /connections/{connection_id}

Delete Connection

CLI:

maton connection delete {connection_id} --yes

maton api -X DELETE /connections/{connection_id}

Specifying Connection

If you have multiple Google Docs connections, specify which one to use:

CLI:

maton google-docs document get <documentId> --connection {connection_id}

maton api /google-docs/v1/documents/<documentId> --connection {connection_id}

Python:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always specify the connection to ensure requests go to the intended account.

---

Security & Permissions

• Access is scoped to Google Docs within the connected Google account.
• All write and delete operations require explicit user approval. Confirm target resource ID and content modifications with the user before executing.

---

API Reference

1. Get Document

Retrieve the full document object including title, structural elements, inline objects, and paragraph styling.

GET /google-docs/v1/documents/{documentId}

Query Parameters:

• suggestionsViewMode - DEFAULT_FOR_CURRENT_ACCESS, PREVIEW_APPROVED, PREVIEW_WITHOUT_SUGGESTIONS, SUGGESTIONS_INLINE.

Example CLI:

maton google-docs document get <documentId>
maton google-docs document get <documentId> --json

---

2. Create Blank Document

Create a new empty Google Doc with a specified title.

POST /google-docs/v1/documents
Content-Type: application/json

{
  "title": "Quarterly Technical Review"
}

Example CLI:

maton google-docs document create --title 'Quarterly Technical Review'

---

3. Append Plain Text to Document

Append plain text to the end of a document body via CLI.

Example CLI:

# Direct text
maton google-docs document write <documentId> --text 'Hello, world!'

# Read from a file
maton google-docs document write <documentId> -F notes.md

# Pipe from stdin
echo 'Piped summary' | maton google-docs document write <documentId> -F -

---

4. Batch Update Document Content & Structure (Rich Formatting)

Perform atomic mutations on document text, formatting, paragraph styles, headers/footers, and inline tables.

POST /google-docs/v1/documents/{documentId}:batchUpdate
Content-Type: application/json

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 1
        },
        "text": "Executive Summary\n\nThis document outlines our cloud migration strategy."
      }
    }
  ]
}

Example CLI:

maton api -X POST /google-docs/v1/documents/<documentId>:batchUpdate \
  -d '{"requests":[{"insertText":{"location":{"index":1},"text":"Hello World\n"}}]}'

Common Request Types for batchUpdate:

1. insertText: Insert text at a specific index location.
2. deleteContentRange: Delete content within a specified range (startIndex and endIndex).
3. replaceAllText: Global search and replace text across document body.

   {
     "replaceAllText": {
       "containsText": {
         "text": "{{PROJECT_NAME}}",
         "matchCase": true
       },
       "replaceText": "SoloQueue v2.0"
     }
   }
   

4. updateTextStyle: Apply bold, italic, font size, or color formatting to range.
5. updateParagraphStyle: Apply heading styles (HEADING_1, HEADING_2, NORMAL_TEXT).

---

Extracting Plain Text from Document Structure

Google Docs API returns content inside body.content as structural elements. To read the plain text of a doc via Python:

import os, json, urllib.request

req = urllib.request.Request('https://api.maton.ai/google-docs/v1/documents/<documentId>')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
doc = json.load(urllib.request.urlopen(req))

text_chunks = []
for element in doc.get('body', {}).get('content', []):
    if 'paragraph' in element:
        for elem in element['paragraph'].get('elements', []):
            if 'textRun' in elem:
                text_chunks.append(elem['textRun'].get('content', ''))

print("".join(text_chunks))

---

Code Examples

CLI

# Create a document
maton google-docs document create --title 'Sprint Planning'

# Write initial notes to the document
maton google-docs document write <documentId> --text 'Sprint 42 Goals:\n- Launch Auth\n- Speed tests'

# Inspect document structure in JSON
maton google-docs document get <documentId> --json

JavaScript

// Get document metadata and content
const response = await fetch(
  'https://api.maton.ai/google-docs/v1/documents/<documentId>',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const doc = await response.json();
console.log(doc.title);

// Create a new document
const createResponse = await fetch(
  'https://api.maton.ai/google-docs/v1/documents',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'RFC: AI Skill Gateway'
    })
  }
);
const newDoc = await createResponse.json();
console.log('Created doc ID:', newDoc.documentId);

Python

import os
import requests

# Get document
response = requests.get(
    'https://api.maton.ai/google-docs/v1/documents/<documentId>',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
doc = response.json()
print(doc.get('title'))

# Create document
create_response = requests.post(
    'https://api.maton.ai/google-docs/v1/documents',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'title': 'RFC: AI Skill Gateway'}
)
print('Created:', create_response.json().get('documentId'))

---

Notes

• Document IDs are opaque strings (extracted from the URL https://docs.google.com/document/d/<documentId>/edit).
• maton google-docs document write appends plain text to the end of the document body. For inserting text at specific indices, replacing text, or applying heading/bold styles, use batchUpdate.
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets 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 or malformed request payload
401	Invalid or missing Maton API key
404	Google Doc ID not found or access denied
429	Rate limit exceeded
5xx	Google Docs API backend error

Troubleshooting: API Key Issues

CLI:

maton whoami
maton connection list google-docs

Manual:

echo $MATON_API_KEY
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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-docs. For example:

• Correct: https://api.maton.ai/google-docs/v1/documents/<documentId>
• Incorrect: https://api.maton.ai/docs/v1/documents/<documentId>

---

Resources

• Google Docs REST API v1 Docs
• Google Docs Batch Update Reference
• Maton CLI Google Docs Manual
• Maton Community
• Maton Support