# Comments operations

> Comment authoring and thread lifecycle operations.



5 operations. Names, descriptions, and behavior flags come from the canonical contract.

## Operations

- [`comments.create`](/document-api/reference/comments/create) (mutates): Create a new comment thread (or reply when parentCommentId is given). Accepts TextAddress / TextTarget anchors, or a TrackedChangeCommentTarget that names a logical tracked-change id. The tracked-change target accepts both the explicit kind form and the Labs-compatible trackedChangeId-only form; the adapter normalizes it to a Word-compatible content anchor on the requested revision side. Callers may supply a durable externalId, or use the v1-compatible caller-supplied commentId alias, plus author fields and arbitrary JSON metadata for integration correlation. The caller-owned id remains distinct from the generated Word-compatible commentId.
- [`comments.patch`](/document-api/reference/comments/patch) (mutates): Patch exactly one field on an existing comment (`text`, `target`, `status`, or `isInternal`). The `target` branch accepts a plain TextAddress or a TrackedChangeCommentTarget, with or without `kind: "trackedChange"`, that names a logical tracked-change id. The legacy `isInternal` input sets or clears the `sdcom:internal` attribute for v1 backward compatibility. Multi-field patches and no-op edits are rejected with `INVALID_INPUT`; reply target / status patches are rejected with `INVALID_CONTEXT`.
- [`comments.delete`](/document-api/reference/comments/delete) (mutates): Remove the targeted comment or reply by ID. Deleting a root does not delete descendant replies.
- [`comments.get`](/document-api/reference/comments/get) (read): Retrieve a single comment thread by ID.
- [`comments.list`](/document-api/reference/comments/list) (read): List all comment threads in the document.