# Google Docs

Google Docs holds briefs, reports and drafts. One API for Agents calls the Google Docs API with read and write access: agents read a document as clean markdown, create new ones, and append, insert or replace text. Documents are opened by ID or URL.

- Provider id: `gdocs`
- Auth: Sign in with Google (OAuth), Service account
- Google scopes: `https://www.googleapis.com/auth/documents`
- Raw endpoints: 3. Smart tools: 5.
- Machine-readable schemas: `GET https://api.oneapiforagents.com/v1/providers/gdocs`

## Smart tools

Curated calls with compact output for agents. Over MCP each one is a tool with the same name.

### docs_read

Read a Google Doc as markdown-style text (headings, lists, tables, links), with its title, revisionId, tabs, heading outline with indexes, and endIndex.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `document` | string | yes | Document ID, or its docs.google.com/document/d/<id>/… URL |
| `tab_id` | string | no | Read one tab only; by default every tab is included |
| `max_chars` | integer | no | Default `50000`. (1000–500000) |
| `suggestions` | string | no | How to show suggested edits; Google's default applies when omitted One of: `DEFAULT_FOR_CURRENT_ACCESS`, `SUGGESTIONS_INLINE`, `PREVIEW_SUGGESTIONS_ACCEPTED`, `PREVIEW_WITHOUT_SUGGESTIONS`. |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gdocs",
    "tool": "docs_read",
    "input": {
      "document": "https://docs.google.com/document/d/1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc/edit"
    }
  }'
```

### docs_create

Create a Google Doc with a title and optional initial text (markdown headings, lists and paragraphs become Docs styles). Returns its ID and URL.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `title` | string | yes |  |
| `text` | string | no |  |
| `format` | string | no | markdown: # headings, - and 1. lists (indent to nest), [links](url), **bold**, *italic*. plain: text as is One of: `markdown`, `plain`. Default `"markdown"`. |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gdocs",
    "tool": "docs_create",
    "input": {
      "title": "Weekly SEO report",
      "text": "# Summary\n- Clicks up 12%"
    }
  }'
```

### docs_append

Append text or simple markdown to the end of a Google Doc (or of one tab).

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `document` | string | yes | Document ID, or its docs.google.com/document/d/<id>/… URL |
| `text` | string | yes |  |
| `format` | string | no | markdown: # headings, - and 1. lists (indent to nest), [links](url), **bold**, *italic*. plain: text as is One of: `markdown`, `plain`. Default `"markdown"`. |
| `tab_id` | string | no | Tab to use; defaults to the tab in the URL, else the first tab |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gdocs",
    "tool": "docs_append",
    "input": {
      "document": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc",
      "text": "## Next steps\n- Refresh the pricing page"
    }
  }'
```

### docs_replace_text

Replace every occurrence of some text in a Google Doc. Case-sensitive unless match_case is false.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `document` | string | yes | Document ID, or its docs.google.com/document/d/<id>/… URL |
| `find` | string | yes |  |
| `replace` | string | yes | Plain text; an empty string deletes the matches |
| `match_case` | boolean | no | Default `true`. |
| `tab_id` | string | no | Only this tab; by default every tab |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gdocs",
    "tool": "docs_replace_text",
    "input": {
      "document": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc",
      "find": "Q3",
      "replace": "Q4"
    }
  }'
```

### docs_insert

Insert text or simple markdown into a Google Doc, either below a heading (matched by its text) or at an index from docs_read. Pass exactly one of heading or index.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `document` | string | yes | Document ID, or its docs.google.com/document/d/<id>/… URL |
| `text` | string | yes |  |
| `format` | string | no | markdown: # headings, - and 1. lists (indent to nest), [links](url), **bold**, *italic*. plain: text as is One of: `markdown`, `plain`. Default `"markdown"`. |
| `heading` | string | no | Heading text to find (case-insensitive; exact match preferred) |
| `placement` | string | no | With heading: right under it, or at the end of its section (before the next heading of the same or higher level) One of: `below_heading`, `end_of_section`. Default `"below_heading"`. |
| `index` | integer | no | UTF-16 index. At a paragraph's start or end the text becomes new paragraphs; mid-paragraph it is inserted inline as plain text (≥ 1) |
| `revision_id` | string | no | revisionId from docs_read; the insert fails if the doc changed since |
| `tab_id` | string | no | Tab to use; defaults to the tab in the URL, else the first tab |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gdocs",
    "tool": "docs_insert",
    "input": {
      "document": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc",
      "heading": "Next steps",
      "text": "- Add FAQ schema"
    }
  }'
```

## Raw endpoints

Passthrough to the provider API. `path` fills URL placeholders, `query` the query string and `body` the JSON body. The response is the provider's own body.

### documents.get

The full Document resource. Pass includeTabsContent=true to get every tab in `tabs` (otherwise `body` holds the first tab only).

`GET https://docs.googleapis.com/v1/documents/{documentId}`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.documentId` | string | yes | Document ID or docs.google.com URL |
| `query.suggestionsViewMode` | string | no | One of: `DEFAULT_FOR_CURRENT_ACCESS`, `SUGGESTIONS_INLINE`, `PREVIEW_SUGGESTIONS_ACCEPTED`, `PREVIEW_WITHOUT_SUGGESTIONS`. |
| `query.includeTabsContent` | boolean | no |  |

```json
{
  "provider": "gdocs",
  "endpoint": "documents.get",
  "input": {
    "path": {
      "documentId": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc"
    },
    "query": {
      "includeTabsContent": true
    }
  }
}
```

### documents.create

Create a blank document. Only `title` is used; add content with documents.batchUpdate.

`POST https://docs.googleapis.com/v1/documents` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `body.title` | string | no |  |

```json
{
  "provider": "gdocs",
  "endpoint": "documents.create",
  "input": {
    "body": {
      "title": "Weekly SEO report"
    }
  }
}
```

### documents.batchUpdate

Apply Docs requests atomically (insertText, deleteContentRange, replaceAllText, createParagraphBullets, …). Indexes are UTF-16 code units; order edits from the highest index down.

`POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate` (writes; needs read-write access)

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.documentId` | string | yes | Document ID or docs.google.com URL |
| `body.requests` | array<object (free-form)> | yes |  |
| `body.writeControl` | object | no |  |

```json
{
  "provider": "gdocs",
  "endpoint": "documents.batchUpdate",
  "input": {
    "path": {
      "documentId": "1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-abc"
    },
    "body": {
      "requests": [
        {
          "insertText": {
            "text": "Hello\n",
            "location": {
              "index": 1
            }
          }
        }
      ]
    }
  }
}
```