# PATCH /api/v2/drive-documents/{drive_document}

Write a document body

- MCP id: drive-documents.update
- Scope: api:write:project_drive
- Scope: api:write:customer_drive
- Scope: api:write:organization_drive
- Scope: api:write:user_drive
- Permission: project_drive::create
- Rate cost: 1 unit, write bucket. A write costs the same whatever `view` you ask for.
- Cache-Control: private, no-store

Replaces or extends a document body.

This is the one route in the API that writes one: the drive item itself carries no body. `content` is GitHub-Flavored Markdown, an empty body is rejected and any key other than `content` and `mode` is a `422`. By default `mode` is `replace`: the Markdown you send becomes the whole document, which overwrites whatever somebody else typed since your last read and discards, permanently, the text colours, highlights, alignment and @mentions Markdown cannot express; read `?include=content_html` on the document first if it may contain them. With `mode: append` the Markdown is added after the existing body and nothing already there is touched, which is the safe way to add notes to a shared document. The write goes through the live collaboration session, so anyone with the document open sees it immediately; if the collaboration server refuses the content, or is unavailable while the document is under collaborative editing, the write is refused with a `422` on `/content` rather than silently lost. Send `If-Match` with the `ETag` from your last read to detect a concurrent edit, which answers `412`. Treat it as best-effort only: this resource carries no revision number and `updated_at` is second-precision, so two writes inside the same second are indistinguishable. The declared permission is `project_drive::create` (editing is part of the create permission); the other three drive prefixes apply by the owning item's owner type, and the record rule is edit access on that item. Note that the owning item being archived does not block this write, even though the item itself then reads as `404` without `trashed=with`; restore the item first if you want plnnrly and the API to agree.

## Parameters
- drive_document (integer, path): The DriveDocument's numeric id.
- view (string, optional): Which field set to render.
- X-Request-Id (header, optional): A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.
- If-Match (header, optional): The ETag a write is conditional on. A stale validator is 412 precondition-failed.

## Request body
- content (string ≤ 262144, required): The document body as GitHub-Flavored Markdown: headings, lists, task lists (`- [ ]`), tables, code fences, links and images all survive. Detail-only: pass `?view=detail` to get it on the collection. Markdown cannot express text colours, highlights, alignment or @mentions, so read `?include=content_html` first if the document may contain them: a read of `content` followed by a PATCH of it discards all four permanently.
- mode (string, optional): Write-only, on update only: `replace` (the default) makes `content` the whole body; `append` adds it after the existing body and keeps everything already there, colours and @mentions included.

Unknown keys are refused with `422` validation-failed, naming the key.

## Response 200
- id (integer, required): Id of the document body, not of the drive item it belongs to. The two are numbered separately.
- drive_item_id (integer, required): The drive item this body belongs to. Set on create and immutable afterwards; read the item itself from `GET /api/v2/drive-items/{drive_item}`.
- content (markdown or null, required, detail only): The document body as GitHub-Flavored Markdown: headings, lists, task lists (`- [ ]`), tables, code fences, links and images all survive. Detail-only: pass `?view=detail` to get it on the collection. Markdown cannot express text colours, highlights, alignment or @mentions, so read `?include=content_html` first if the document may contain them: a read of `content` followed by a PATCH of it discards all four permanently.
- created_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Creation timestamp.
- updated_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Last-write timestamp; use for incremental sync. Typing in the collaborative editor moves this, not the drive item's own `updated_at`.
- links (DriveDocumentLinks, required)
  - self (url, required): The canonical URI of this record.
- content_html (html or null, optional, on request): The same document as sanitised HTML, preserving the text colours, highlights, alignment and @mentions Markdown cannot carry. Mention spans round-trip unchanged; constructing a new one is out of scope for v2.0.

## Errors
- 403 forbidden-by-policy | insufficient-permission | insufficient-token-scope: Forbidden.
- 412 precondition-failed: Precondition failed.
- 415 unsupported-media-type: Unsupported media type.
- 422 unprocessable-relationship | validation-failed: Unprocessable content.
- 400 idempotency-key-required | invalid-cursor | invalid-query-parameter | malformed-request | unsupported-parameter: Bad request.
- 401 token-expired | unauthenticated: Unauthenticated.
- 404 endpoint-not-found | resource-not-found: Not found.
- 406 not-acceptable: Not acceptable.
- 429 rate-limit-exceeded: Too many requests.
- 500 internal-error: Server error.
- 503 tenant-unavailable: Service unavailable.

## Example
```bash
curl -X PATCH \
  'https://<your-url>/api/v2/drive-documents/1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: *' \
  -d '{
    "content": "# Kick-off\n\nConfirmed for Monday 09:00.\n"
  }'
```