Google Docs API Comments & Suggested Edits: ISV Guide

08 Oct 2026

9 min

Automation

Enterprise

Implementation

Google's Docs, Sheets, and Slides APIs now let third-party applications programmatically create, read, reply to, and delete comments, and the Docs API also supports submitting proposed text changes as suggestions, not just hard edits. The release went generally available on September 30, 2026, which means an external system can now stage a reviewable change in a shared Google Doc instead of overwriting the document outright, closing a gap that integration builders have worked around for years.

That one detail, suggestions are Docs-only, changes how you should architect any integration that needs a human-in-the-loop review step before a document gets finalized and routed for signature.

What exactly shipped on September 30, 2026?

Google marked the Google Docs, Sheets, and Slides API comment support as generally available, with a gradual rollout of up to 15 days across Rapid Release and Scheduled Release domains. Per the Google Workspace developer release notes, each API got a slightly different slice of functionality:

Docs API (v1): read comment threads and anchors (commentsViewMode on documents.get), create threads and replies (InsertCommentRequest, AddCommentReplyRequest), edit posts (UpdateCommentPostRequest), delete comments and replies, and write suggestions by setting writeControl.writeMode to SUGGEST in documents.batchUpdate.
Sheets API (v4): read, create, reply to, update, and delete comments anchored to specific cells, using the same commentsViewMode and request pattern as Docs.
Slides API (v1): the same comment lifecycle, anchored to individual slides and specific elements on a slide.

Only Docs got suggestions. Sheets and Slides got comments. That is not an oversight, it is the shape of the product: Sheets and Slides do not have a "suggesting mode" for end users either, so the API surface mirrors the editor.

One more detail worth flagging for anyone building on top of Gemini or an agent framework: according to Google's own announcement, programmatic comment support inside the Docs, Sheets, and Slides MCP servers remains in developer preview, separate from the general-availability status of the REST APIs themselves. If you are wiring an AI agent to Google Docs through MCP rather than calling the REST API directly, check which surface you are actually targeting before you promise a client that comment support is production-ready.

How do you create a suggestion with the Docs API instead of a hard edit?

You call documents.batchUpdate with the standard text-insertion or text-replacement requests, but you set writeControl.writeMode to SUGGEST at the top level of the request body instead of leaving it at the default UPDATE mode. A minimal example:

json

POST https://docs.googleapis.com/v1/documents/DOCUMENT_ID:batchUpdate
{
  "requests": [
    {
      "insertText": {
        "location": { "index": 25 },
        "text": "subject to a 30-day termination notice"
      }
    }
  ],
  "writeControl": {
    "writeMode": "SUGGEST"
  }
}

The same request with writeMode left as UPDATE would silently overwrite the document text. With SUGGEST, it shows up as a pending suggestion, exactly like a human collaborator typing in suggesting mode, and a reviewer has to accept or reject it before it becomes part of the document. Google's own developer guide for working with comments and suggestions is worth reading end to end before you ship this, because it also flags that batch updates touching comments or suggestions can partially fail, so you need to check the response for per-request errors rather than assuming the whole batch succeeded or failed together.

What can ISVs actually build with this that they could not build before?

Before this release, an integration that needed a human to approve an AI-drafted or system-generated change to a Google Doc had exactly two bad options: overwrite the live document and hope nobody minds losing the paper trail, or export the whole document, diff it externally, and re-import it as a new file. Neither preserves the collaborative, in-document review experience that Google Docs users already expect.

With suggestions now available through the API, a few integration patterns become straightforward:

AI drafting tools that propose, not overwrite. A contract-drafting assistant, a style-guide enforcer, or an AI research tool can call documents.batchUpdate with writeMode: SUGGEST to stage every change it wants to make, then let a human accept or reject each one inline, the same workflow lawyers and editors already use for human redlines.

Project-tracker to document sync. A ticketing or project-management tool can post a comment directly on the paragraph or cell that a ticket references, instead of pasting a link into a sidebar chat that gets lost. Comments can be read back programmatically too, so the integration can poll for replies and close the loop, updating ticket status when a reviewer resolves the thread.

Pre-signature staging for agreement workflows. This is the one that matters most for anyone building around Docusign. A contract-adjacent application can now stage proposed language changes and open questions as comments and suggestions directly in a shared Google Doc, let legal and business stakeholders negotiate inline, and only move the document into a signature workflow once every suggestion is resolved and every comment thread is closed. That is a meaningfully different integration shape than round-tripping the entire document through an external review tool and re-uploading it each time something changes.

That last pattern is where the Docusign comparison actually lands, and it is worth being precise about it rather than hand-waving. Docusign's own contract lifecycle tooling already has a mature AI-powered review and redlining experience, built on Docusign Iris, for negotiating contract language before signature. What Google's update does is not replace that, it extends the same proposal-then-approve discipline into the Google Docs surface that a huge number of teams already use for early-stage drafting, before a document is formal enough to enter a CLM or signature pipeline at all. If your integration's job is to carry a document from "a shared Google Doc two people are negotiating" to "a finalized agreement ready for Docusign," you now have a native way to represent the negotiation step itself, instead of treating the Google Doc as a dumb file you fetch once at the end.

Where does this break if you are not careful?

A few integration pitfalls to plan for before you ship:

Suggestions are Docs-only. If your product also touches Sheets or Slides and needs a reviewable, non-destructive write, you cannot use suggestion mode there. Route that review step through comments instead, anchored to the relevant cell or slide element, and build your own accept/reject affordance in your product UI rather than relying on the editor's native suggestion state.
Partial batch failures. Because batchUpdate requests involving comments or suggestions can partially fail, treat every batch as a set of independently-reportable operations in your error handling, not an all-or-nothing transaction.
MCP is not the REST API. If part of your stack calls Docs, Sheets, or Slides through an MCP server rather than directly, remember that comment support there is still developer preview. Build a fallback to the REST API for any comment or suggestion workflow you need to guarantee in production.
Rollout timing. The gradual rollout window of up to 15 days means your integration might behave inconsistently across customer domains for a couple of weeks after a release like this. Do not hard-code an assumption that every tenant has the feature live on day one.

How does this relate to Docusign Workflow Builder and other signature tooling?

Once the negotiation step inside a Google Doc is finished, the natural next move for an agreement-shaped integration is to kick off a Docusign Workflow Builder (formerly Maestro) run that takes the finalized document into signature, approvals, and routing. That handoff is exactly where a lot of custom integrations quietly break: the triggering event comes from a third system (a CRM stage change, a resolved comment thread, a status flip in your own app), and that event has to reliably reach Docusign without silent drops. If that triggering and webhook-reliability layer is the part of your stack you are worried about, Baton exists specifically to relay webhooks into Docusign Workflow Builder with HMAC verification, retries, and central logging, so the comment-resolution event in your product does not just disappear if a request times out.

For teams building the review-to-signature pipeline end to end, fluidlabs has covered the four start methods for Docusign Workflow Builder and the broader pattern of triggering workflows from any platform, both useful reading once your Google Docs comment and suggestion logic is in place and you are ready to wire up the next step.

FAQ

Does the Google Sheets API support suggested edits like the Docs API does? No. The Sheets API and Slides API only support programmatic comments, not suggestions. Suggested edits, where a proposed text change sits in a pending state until accepted or rejected, are a Docs API-only capability as of the September 30, 2026 release, per Google's own announcement.

How do I set a suggestion instead of a direct edit in the Docs API? Set writeControl.writeMode to SUGGEST in your documents.batchUpdate request body. Leaving it at the default UPDATE mode applies the change directly instead of staging it as a reviewable suggestion, according to the Google developer release notes.

Is comment support available through the Google Docs MCP server? Not fully in production yet. Google states that programmatic comment support within the Docs, Sheets, and Slides MCP servers remains in developer preview, even though the underlying REST APIs are generally available.

Does this replace Docusign's redlining tools for contract negotiation? No. Docusign's contract lifecycle tooling already provides an AI-assisted review and redlining workflow built for formal contract negotiation. Google's update gives integration builders a way to stage reviewable changes earlier, inside a shared Google Doc, before a document is ready to enter a signature or CLM pipeline.

Where to go from here

If you are building an ISV integration that needs to move a document from collaborative drafting in Google Docs to a signed agreement in Docusign, the comment and suggestion gap is closed on the Google side, but the handoff between the two systems still has to be designed deliberately: what event marks a document "ready," how that event reaches Docusign reliably, and what Workflow Builder does with it once it arrives. Talk to the fluidlabs team about building that pipeline, or browse the Docusign IAM resources library for more on the workflow side of the handoff.