create.contentControl
Create a new content control (SDT) in the document, optionally seeded with plain text or structured block preset content. Inline plain-text creation at a selection inherits the document run formatting at the caret or first selected character when inline is omitted; pending browser caret overrides are excluded. To include pending overrides, capture format.readSelection({ selection: "current" }) and pass its uniform values through inline. An explicit inline payload supplies fontFamily, fontSize, bold, italic, underline and strike values instead, with unspecified properties inheriting from the destination paragraph. It requires explicit content and commits formatting, content, tag and lockMode in one undoable operation. If inherited formatting cannot be resolved, creation returns CAPABILITY_UNAVAILABLE without changing the document or history; pass explicit inline values to bypass automatic inheritance.
doc.create.contentControl(…)Expected result
Returns a ContentControlMutationResult with the created content control target.
Inputs
kind"block" | "inline"requiredcontentstringconditionally required9 additional input fields
controlTypestringtargetobjectFields
kind"block" | "inline"requirednodeType"sdt"requirednodeIdstringrequiredstoryStoryLocatorStory 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"requiredstoryType"body"requiredheaderFooterSlot
kind"story"requiredstoryType"headerFooterSlot"requiredsectionSectionAddressrequiredheaderFooterKind"header" | "footer"requiredvariant"default" | "first" | "even"requiredresolution"effective" | "explicit"onWrite"materializeIfInherited" | "editResolvedPart" | "error"headerFooterPart
kind"story"requiredstoryType"headerFooterPart"requiredrefIdstringrequiredfootnote
kind"story"requiredstoryType"footnote"requirednoteIdstringrequiredendnote
kind"story"requiredstoryType"endnote"requirednoteIdstringrequiredtextbox
kind"story"requiredstoryType"textbox"requiredtextboxIdstringrequiredatSelectionTargetFields
captureStatestringOpaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing.
kind"selection"requiredstartSelectionPointrequiredA 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"requiredblockIdstringrequiredoffsetintegerrequiredstoryStoryLocatorStory 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"requiredstoryType"body"requiredheaderFooterSlot
kind"story"requiredstoryType"headerFooterSlot"requiredsectionSectionAddressrequiredheaderFooterKind"header" | "footer"requiredvariant"default" | "first" | "even"requiredresolution"effective" | "explicit"onWrite"materializeIfInherited" | "editResolvedPart" | "error"headerFooterPart
kind"story"requiredstoryType"headerFooterPart"requiredrefIdstringrequiredfootnote
kind"story"requiredstoryType"footnote"requirednoteIdstringrequiredendnote
kind"story"requiredstoryType"endnote"requirednoteIdstringrequiredtextbox
kind"story"requiredstoryType"textbox"requiredtextboxIdstringrequirednodeEdge
kind"nodeEdge"requirednodeSelectionEdgeNodeAddressrequirededge"before" | "after"requiredendSelectionPointrequiredA 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"requiredblockIdstringrequiredoffsetintegerrequiredstoryStoryLocatorStory 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"requiredstoryType"body"requiredheaderFooterSlot
kind"story"requiredstoryType"headerFooterSlot"requiredsectionSectionAddressrequiredheaderFooterKind"header" | "footer"requiredvariant"default" | "first" | "even"requiredresolution"effective" | "explicit"onWrite"materializeIfInherited" | "editResolvedPart" | "error"headerFooterPart
kind"story"requiredstoryType"headerFooterPart"requiredrefIdstringrequiredfootnote
kind"story"requiredstoryType"footnote"requirednoteIdstringrequiredendnote
kind"story"requiredstoryType"endnote"requirednoteIdstringrequiredtextbox
kind"story"requiredstoryType"textbox"requiredtextboxIdstringrequirednodeEdge
kind"nodeEdge"requirednodeSelectionEdgeNodeAddressrequirededge"before" | "after"requiredstoryStoryLocatorStory 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"requiredstoryType"body"requiredheaderFooterSlot
kind"story"requiredstoryType"headerFooterSlot"requiredsectionSectionAddressrequiredheaderFooterKind"header" | "footer"requiredvariant"default" | "first" | "even"requiredresolution"effective" | "explicit"onWrite"materializeIfInherited" | "editResolvedPart" | "error"headerFooterPart
kind"story"requiredstoryType"headerFooterPart"requiredrefIdstringrequiredfootnote
kind"story"requiredstoryType"footnote"requirednoteIdstringrequiredendnote
kind"story"requiredstoryType"endnote"requirednoteIdstringrequiredtextbox
kind"story"requiredstoryType"textbox"requiredtextboxIdstringrequiredcoordinateSpaceTextCoordinateSpacetagstringaliasstringlockMode"unlocked" | "sdtLocked" | "contentLocked" | "sdtContentLocked"htmlstringjsonobject | object[]Variant 1
No fields.
Variant 2
No fields.
inlineobjectFields
boldboolean | nullVariant 1
No fields.
Variant 2
No fields.
italicboolean | nullVariant 1
No fields.
Variant 2
No fields.
strikeboolean | nullVariant 1
No fields.
Variant 2
No fields.
underlineboolean | null | objectVariant 1
No fields.
Variant 2
No fields.
Variant 3
stylestring | nullVariant 1
No fields.
Variant 2
No fields.
colorstring | nullVariant 1
No fields.
Variant 2
No fields.
themeColorstring | nullVariant 1
No fields.
Variant 2
No fields.
fontSizenumber | nullVariant 1
No fields.
Variant 2
No fields.
fontFamilystring | nullVariant 1
No fields.
Variant 2
No fields.
Result
Output fields
true
status"NO_OP"changeTagstringCaller correlation for this commit only; never persisted or replayed on Undo/Redo.
temporaryobjectFields
idstringrequiredphase"begin" | "replace" | "rollback" | "commit"requiredtagstringrequiredonNativeEdit"cancel" | "preserve"cancelledBy"native-edit"appliedChangeMode"direct" | "tracked"idstringinsertedEntityAddress[]updatedEntityAddress[]removedEntityAddress[]invalidatedRefsAffectedRef[]remappedRefsAffectedRefRemapping[]affectedStoriesStoryLocator[]textRangeShiftsTextRangeShift[]trackedTextRangeShiftsTrackedTextRangeShift[]txIdstringwarningsReviewWarning[]effectsReceiptEffectsFields
insertedTextTextMutationEffect[]insertedBlocksBlockMutationEffect[]resultTextTextTargetFields
captureStatestringOpaque browser selection capture state. Preserve it when passing a selection target to comments.create. Changed or unverifiable state is refused before writing.
kind"text"requiredsegmentsTextSegment[]requiredstoryStoryLocatorStory 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"requiredstoryType"body"requiredheaderFooterSlot
kind"story"requiredstoryType"headerFooterSlot"requiredsectionSectionAddressrequiredheaderFooterKind"header" | "footer"requiredvariant"default" | "first" | "even"requiredresolution"effective" | "explicit"onWrite"materializeIfInherited" | "editResolvedPart" | "error"headerFooterPart
kind"story"requiredstoryType"headerFooterPart"requiredrefIdstringrequiredfootnote
kind"story"requiredstoryType"footnote"requirednoteIdstringrequiredendnote
kind"story"requiredstoryType"endnote"requirednoteIdstringrequiredtextbox
kind"story"requiredstoryType"textbox"requiredtextboxIdstringrequiredcoordinateSpaceTextCoordinateSpacetrackedChangeRefsTrackedChangeAddress[]trackedChangeCountintegerchangedbooleansuccesstruerequiredcontentControlobjectrequiredFields
kind"block" | "inline"requirednodeType"sdt"requirednodeIdstringrequiredstoryStoryLocatorStory 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"requiredstoryType"body"requiredheaderFooterSlot
kind"story"requiredstoryType"headerFooterSlot"requiredsectionSectionAddressrequiredheaderFooterKind"header" | "footer"requiredvariant"default" | "first" | "even"requiredresolution"effective" | "explicit"onWrite"materializeIfInherited" | "editResolvedPart" | "error"headerFooterPart
kind"story"requiredstoryType"headerFooterPart"requiredrefIdstringrequiredfootnote
kind"story"requiredstoryType"footnote"requirednoteIdstringrequiredendnote
kind"story"requiredstoryType"endnote"requirednoteIdstringrequiredtextbox
kind"story"requiredstoryType"textbox"requiredtextboxIdstringrequiredcreatedBlockIdstringupdatedRefobjectFields
kind"block" | "inline"requirednodeType"sdt"requirednodeIdstringrequiredstoryStoryLocatorStory 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"requiredstoryType"body"requiredheaderFooterSlot
kind"story"requiredstoryType"headerFooterSlot"requiredsectionSectionAddressrequiredheaderFooterKind"header" | "footer"requiredvariant"default" | "first" | "even"requiredresolution"effective" | "explicit"onWrite"materializeIfInherited" | "editResolvedPart" | "error"headerFooterPart
kind"story"requiredstoryType"headerFooterPart"requiredrefIdstringrequiredfootnote
kind"story"requiredstoryType"footnote"requirednoteIdstringrequiredendnote
kind"story"requiredstoryType"endnote"requirednoteIdstringrequiredtextbox
kind"story"requiredstoryType"textbox"requiredtextboxIdstringrequiredfalse
successfalserequiredfailureReceiptFailurerequiredFields
codestringrequiredmessagestringrequireddetailsunknownFailures
Pre-apply throws
TARGET_NOT_FOUNDINVALID_TARGETAMBIGUOUS_TARGET
4 more codes
INVALID_INPUTLOCK_VIOLATIONREVISION_MISMATCHCAPABILITY_UNAVAILABLE
Non-applied receipt codes
INVALID_TARGETNO_OP
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