# DriveDocument

The body of a drive item of kind `document`: the rich-editor content plnnrly opens when you click a document in the file browser. It is stored separately from the item, so the item's own metadata (title, folder, tags, owner, access) lives on the drive item and is not repeated here. The body is exchanged as GitHub-Flavored Markdown, with a sanitised-HTML projection available on demand for the colours, highlights, alignment and mentions Markdown cannot express. Access is inherited whole from the owning drive item: a caller who may read that item may read its body, and a caller who may edit it may write one.

## Used by
- GET /api/v2/drive-documents: List document bodies (DriveDocumentList)
- POST /api/v2/drive-documents: Create a document body (DriveDocument)
- GET /api/v2/drive-documents/{drive_document}: Read a document body (DriveDocument)
- PATCH /api/v2/drive-documents/{drive_document}: Write a document body (DriveDocument)

## DriveDocument fields
- 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.

Only on `?view=detail`: content

## Variants

### DriveDocumentList

What a collection returns, and what `?view=summary` returns on a single record.

6 fields.
Omits: content

### DriveDocumentLinks

The `links` object on this resource.

Keys: self

## Example
```json
{
  "id": 1,
  "drive_item_id": 1,
  "content": "# Kick-off\n\n- [ ] Confirm scope with the client\n- [x] Book the room\n",
  "content_html": "<p>…</p>",
  "created_at": "2026-03-04T09:15:00Z",
  "updated_at": "2026-03-04T09:15:00Z",
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1"
  }
}
```