# 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. - Member path: `doc.comments.create(…)` - Mutates document: yes - Idempotency: `non-idempotent` - Supports tracked mode: no - Supports dry run: no ## 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. 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`. ## Input schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "TextAddress": { "type": "object", "properties": { "kind": { "const": "text" }, "blockId": { "type": "string" }, "range": { "$ref": "#/$defs/Range" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "range" ] }, "Range": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } }, "additionalProperties": false, "required": [ "start", "end" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "body" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterPart" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "footnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "endnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "textbox" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "TextTarget": { "type": "object", "properties": { "kind": { "const": "text" }, "segments": { "type": "array", "items": { "$ref": "#/$defs/TextSegment" }, "minItems": 1 }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "segments" ] }, "TextSegment": { "type": "object", "properties": { "blockId": { "type": "string" }, "range": { "$ref": "#/$defs/Range" } }, "additionalProperties": false, "required": [ "blockId", "range" ] }, "TextCoordinateSpace": { "enum": [ "visible", "tracked" ] }, "SelectionTarget": { "type": "object", "properties": { "kind": { "const": "selection" }, "start": { "$ref": "#/$defs/SelectionPoint" }, "end": { "$ref": "#/$defs/SelectionPoint" }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "start", "end" ] }, "SelectionPoint": { "description": "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.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text" }, "blockId": { "type": "string" }, "offset": { "type": "integer", "minimum": 0 }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "offset" ] }, { "type": "object", "properties": { "kind": { "const": "nodeEdge" }, "node": { "$ref": "#/$defs/SelectionEdgeNodeAddress" }, "edge": { "enum": [ "before", "after" ] } }, "additionalProperties": false, "required": [ "kind", "node", "edge" ] } ] }, "SelectionEdgeNodeAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "enum": [ "paragraph", "heading", "table", "tableOfContents", "sdt", "image" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "CommentTrackedChangeTarget": { "type": "object", "properties": { "kind": { "const": "trackedChange", "description": "Optional discriminator. Omit it for the Labs-compatible { trackedChangeId } shape." }, "trackedChangeId": { "type": "string" }, "side": { "enum": [ "inserted", "deleted", "source", "destination" ], "description": "Which revision side to anchor the comment on. Optional for paired replacements (defaults to inserted) and paired moves (defaults to destination); required for independent replacements where both sides are separately reviewable." }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "trackedChangeId" ] } }, "type": "object", "properties": { "text": { "type": "string", "description": "Comment text content." }, "target": { "description": "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 .", "oneOf": [ { "$ref": "#/$defs/TextAddress" }, { "$ref": "#/$defs/TextTarget" }, { "$ref": "#/$defs/SelectionTarget" }, { "$ref": "#/$defs/CommentTrackedChangeTarget" }, { "type": "object", "properties": { "text": { "type": "string", "description": "Text to find and anchor the comment to. The adapter resolves the first body/story match." }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "text" ] } ] }, "trackedChangeId": { "type": "string", "description": "Compatibility shorthand for target: { trackedChangeId }. Used only when target is omitted." }, "side": { "enum": [ "inserted", "deleted", "source", "destination" ], "description": "Optional side for the top-level trackedChangeId shorthand." }, "story": { "$ref": "#/$defs/StoryLocator", "description": "Optional story for the top-level trackedChangeId shorthand." }, "parentCommentId": { "type": "string", "description": "Parent comment ID for creating a threaded reply." }, "parentId": { "type": "string", "description": "Public alias for parentCommentId when creating a threaded reply." }, "commentId": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Compatibility alias for externalId, matching the caller-supplied commentId accepted by the v1 editor. V2 still generates a separate Word-compatible commentId." }, "externalId": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Caller-owned durable, document-unique integration id. Kept separate from the generated Word-compatible commentId." }, "author": { "type": "string", "minLength": 1, "description": "Author display name. Defaults to the configured session author." }, "authorId": { "type": "string", "minLength": 1, "description": "Stable caller-owned author id." }, "authorEmail": { "type": "string", "minLength": 1, "description": "Caller-owned author email." }, "authorImage": { "type": "string", "minLength": 1, "description": "Caller-owned author image URL." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Caller-owned JSON metadata persisted with the comment." } }, "additionalProperties": false, "required": [ "text" ] } ``` ## Output schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "CommentsCreateSuccess": { "type": "object", "properties": { "success": { "const": true }, "id": { "type": "string" }, "inserted": { "type": "array", "items": { "$ref": "#/$defs/EntityAddress" } }, "updated": { "type": "array", "items": { "$ref": "#/$defs/EntityAddress" } }, "removed": { "type": "array", "items": { "$ref": "#/$defs/EntityAddress" } } }, "additionalProperties": false, "required": [ "success", "id" ] }, "EntityAddress": { "oneOf": [ { "$ref": "#/$defs/CommentAddress" }, { "$ref": "#/$defs/TrackedChangeAddress" } ] }, "CommentAddress": { "type": "object", "properties": { "kind": { "const": "entity" }, "entityType": { "const": "comment" }, "entityId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "entityType", "entityId" ] }, "TrackedChangeAddress": { "type": "object", "properties": { "kind": { "const": "entity" }, "entityType": { "const": "trackedChange" }, "entityId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "entityType", "entityId" ] }, "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "body" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterPart" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "footnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "endnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "textbox" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] } }, "oneOf": [ { "$ref": "#/$defs/CommentsCreateSuccess" }, { "type": "object", "properties": { "success": { "const": false }, "failure": { "type": "object", "properties": { "code": { "enum": [ "INVALID_INPUT", "INVALID_TARGET", "INVALID_CONTEXT", "TARGET_NOT_FOUND", "CAPABILITY_UNAVAILABLE" ] }, "message": { "type": "string" }, "details": {} }, "additionalProperties": false, "required": [ "code", "message" ] } }, "additionalProperties": false, "required": [ "success", "failure" ] } ] } ``` ## Pre-apply throws - `TARGET_NOT_FOUND` - `CAPABILITY_UNAVAILABLE` - `INVALID_TARGET` - `INVALID_INPUT` ## Non-applied receipt codes - `INVALID_INPUT` - `INVALID_TARGET` - `INVALID_CONTEXT` - `TARGET_NOT_FOUND` - `CAPABILITY_UNAVAILABLE`