update-drive-document-tool

Renames a document and/or writes to its body, returning the document in the same shape get-drive-document-tool uses plus an applied block describing what happened.

Writes go through the live collaboration session, so anyone with the document open in a browser sees the change immediately and nobody's in-flight typing is lost.

Inputs

Name	Type	Required	Description
`document_id`	integer	yes	The drive document id.
`title`	string	no	New title. Omit to leave it alone.
`content`	string	no	Body to write, up to 262144 characters.
`format`	string	no	Format of `content`: `markdown` (default) or `html`.
`mode`	string	no	`append` (default) or `replace`.
`expected_version`	string	conditional	The `version` from your last read. Required to `replace` a document that is under collaborative editing.

At least one of title or content must be given.

Choosing a mode

append adds to the end of the document. It can never remove anything, which is why it is the default and the right choice for meeting notes, changelog entries, status updates and anything additive.

replace swaps the whole body. It permanently discards everything Markdown cannot express — colours, highlights, alignment, mathematical expressions, and the identity behind any @mention. If the document may contain those, read it with format: "html" first and send HTML back, or use append instead.

Replacing a document that is under collaborative editing requires expected_version. Read the document, keep the version from the response, and pass it back; if anyone changed the document in the meantime the write is refused and you can re-read and retry. There remains a very small window between the check and the write in which a keystroke can be lost — the collaboration server merges rather than corrupts, but a replace is still a blunt instrument on a document someone is actively typing in.

Permissions

The caller needs drive access for the document's owner and edit access to the document itself. View access is not enough. A document the caller cannot see and an id that does not exist return an identical error.

Example

{
  "document_id": 55,
  "content": "## 19 August\n\n- Reviewed the migration plan\n- [ ] Chase the sign-off\n",
  "mode": "append"
}

Response

The full document snapshot, plus:

{
  "applied": {
    "title_changed": false,
    "content_written": true,
    "mode": "append",
    "written_via": "collaboration_server",
    "version_before": "9f2c41ab77e0d3b5",
    "version_after": "2b7d90e4c1aa6f38"
  }
}

written_via is collaboration_server in the normal case. It reads database only for a document nobody has ever opened in the editor, written directly because the collaboration server was unreachable.

Errors

A caller with only view access returns an authorization error.
Writing content to an uploaded file (PDF, image, Office document) returns a validation error — those have no editable body.
A replace on a collaboratively edited document without expected_version, or with a stale one, returns a validation error and nothing is written.
If the collaboration server is unreachable, a write to a document under collaborative editing is refused rather than being applied somewhere it would be silently overwritten.
Passing neither title nor content returns a validation error.