Document apiReferenceComments

comments.create

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. Pass expectedText with a single-paragraph text target to refuse the comment when the text at that target has changed since it was selected.

mutates documentnon-idempotent
doc.comments.create(…)

Expected result

Returns a Receipt with the new commentId in `id` and `inserted` on success; rejects whitespace-only bodies, unsupported anchor contexts, and cross-story targets. When expectedText is given and the target text differs, fails with `PRECONDITION_FAILED` before any change. Tracked-change comment targets support insertion, deletion, replacement, and paired-move revisions; they fail with `TARGET_NOT_FOUND` for stale ids, `CAPABILITY_UNAVAILABLE` for formatting / structural revisions and unpaired move sides, and `INVALID_TARGET` for incompatible side requests or ambiguous replacement targets that omit a required `side`.

Inputs

textstringrequired

Comment text content.

14 additional input fields
targetTextAddress | TextTarget | SelectionTarget | CommentTrackedChangeTarget | object

Text range to anchor the comment. Accepts either a single-block TextAddress {kind:'text', blockId, range}, a multi-segment TextTarget {kind:'text', segments:[{blockId, range}, ...]} for selections that span blocks, a SelectionTarget {kind:'selection', start, end} returned by query.match, a TextSearchCommentTarget {text, story?}, or a TrackedChangeCommentTarget ({kind:'trackedChange', trackedChangeId, side?} or {trackedChangeId, side?}) that names a logical tracked-change id as a convenience anchor .

TextAddress
captureStatestring

Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing.

kind"text"required
blockIdstringrequired
rangeRangerequired
Fields
startintegerrequired
endintegerrequired
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
TextTarget
captureStatestring

Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing.

kind"text"required
segmentsTextSegment[]required
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
coordinateSpaceTextCoordinateSpace
SelectionTarget
captureStatestring

Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing.

kind"selection"required
startSelectionPointrequired

A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.

text
kind"text"required
blockIdstringrequired
offsetintegerrequired
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
nodeEdge
kind"nodeEdge"required
nodeSelectionEdgeNodeAddressrequired
edge"before" | "after"required
endSelectionPointrequired

A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.

text
kind"text"required
blockIdstringrequired
offsetintegerrequired
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
nodeEdge
kind"nodeEdge"required
nodeSelectionEdgeNodeAddressrequired
edge"before" | "after"required
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
coordinateSpaceTextCoordinateSpace
CommentTrackedChangeTarget
kind"trackedChange"

Optional discriminator. Omit it for the Labs-compatible { trackedChangeId } shape.

trackedChangeIdstringrequired
side"inserted" | "deleted" | "source" | "destination"

Which revision side to anchor the comment on. Optional for grouped replacements (defaults to inserted) and paired moves (defaults to destination); required for separate replacements where both sides are reviewed independently.

storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
Variant 5
textstringrequired

Text to find and anchor the comment to. The adapter resolves the first body/story match.

storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
trackedChangeIdstring

Compatibility shorthand for target: { trackedChangeId }. Used only when target is omitted.

side"inserted" | "deleted" | "source" | "destination"

Optional side for the top-level trackedChangeId shorthand.

storyStoryLocator

Optional story for the top-level trackedChangeId shorthand.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
Fields
kind"section"required
sectionIdstringrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
parentCommentIdstring

Parent comment ID for creating a threaded reply.

parentIdstring

Public alias for parentCommentId when creating a threaded reply.

commentIdstring

Compatibility alias for externalId, matching the caller-supplied commentId accepted by the v1 editor. V2 still generates a separate Word-compatible commentId.

externalIdstring

Caller-owned durable, document-unique integration id. Kept separate from the generated Word-compatible commentId.

authorstring

Author display name. Defaults to the configured session author.

authorIdstring

Stable caller-owned author id.

authorEmailstring

Caller-owned author email.

authorImagestring

Caller-owned author image URL.

metadataobject

Caller-owned JSON metadata persisted with the comment.

expectedTextstring

Require the exact text currently at target before creating the comment. Pass the text the user selected, such as selection.current({ includeText: true }).text. A mismatch fails with PRECONDITION_FAILED and creates nothing. Only single-paragraph text targets support this guard; it checks the words, so it does not tell repeated identical text apart.

Result

Output fields
true
successtruerequired
status"NO_OP"
changeTagstring

Caller correlation for this commit only; never persisted or replayed on Undo/Redo.

temporaryobject
Fields
idstringrequired
phase"begin" | "replace" | "rollback" | "commit"required
tagstringrequired
onNativeEdit"cancel" | "preserve"
cancelledBy"native-edit"
appliedChangeMode"direct" | "tracked"
idstringrequired
insertedEntityAddress[]
updatedEntityAddress[]
removedEntityAddress[]
invalidatedRefsAffectedRef[]
remappedRefsAffectedRefRemapping[]
affectedStoriesStoryLocator[]
textRangeShiftsTextRangeShift[]
trackedTextRangeShiftsTrackedTextRangeShift[]
txIdstring
warningsReviewWarning[]
effectsReceiptEffects
Fields
insertedTextTextMutationEffect[]
insertedBlocksBlockMutationEffect[]
resultTextTextTarget
Fields
captureStatestring

Opaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing.

kind"text"required
segmentsTextSegment[]required
storyStoryLocator

Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.

body
kind"story"required
storyType"body"required
headerFooterSlot
kind"story"required
storyType"headerFooterSlot"required
sectionSectionAddressrequired
headerFooterKind"header" | "footer"required
variant"default" | "first" | "even"required
resolution"effective" | "explicit"
onWrite"materializeIfInherited" | "editResolvedPart" | "error"
headerFooterPart
kind"story"required
storyType"headerFooterPart"required
refIdstringrequired
footnote
kind"story"required
storyType"footnote"required
noteIdstringrequired
endnote
kind"story"required
storyType"endnote"required
noteIdstringrequired
textbox
kind"story"required
storyType"textbox"required
textboxIdstringrequired
coordinateSpaceTextCoordinateSpace
trackedChangeRefsTrackedChangeAddress[]
trackedChangeCountinteger
changedboolean
historyHistoryReplay
Fields
txIdstringrequired
direction"undo" | "redo"required
txIdsstring[]
false
successfalserequired
failureobjectrequired
Fields
code"INVALID_INPUT" | "INVALID_TARGET" | "INVALID_CONTEXT" | "TARGET_NOT_FOUND" | "CAPABILITY_UNAVAILABLE" | "PRECONDITION_FAILED"required
messagestringrequired
detailsunknown

Failures

Pre-apply throws

  • TARGET_NOT_FOUND
  • CAPABILITY_UNAVAILABLE
  • INVALID_TARGET
1 more codes
  • INVALID_INPUT

Non-applied receipt codes

  • INVALID_INPUT
  • INVALID_TARGET
  • INVALID_CONTEXT
3 more codes
  • TARGET_NOT_FOUND
  • CAPABILITY_UNAVAILABLE
  • PRECONDITION_FAILED

Raw schemas

Open the generated JSON artifact for the exact input, output, success, and failure schemas represented by this contract version.

View raw JSON schemas