Document apiReferenceFields
fields.insert
Insert a raw field code at a target location, optionally preserving cached result text. The current v1 runtime supports rebuild flows; `cachedResultText` / `updatePolicy: "preserveCached"` currently return `CAPABILITY_UNAVAILABLE`.
mutates documentdry runnon-idempotent
doc.fields.insert(…)Expected result
Returns a FieldMutationResult indicating success with the field address or a failure.
Inputs
mode"raw"requiredatTextTargetrequiredFields
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"requiredtextboxIdstringrequiredinstructionstringrequired2 additional input fields
cachedResultTextstringupdatePolicy"rebuild" | "preserveCached"Result
Output fields
true
successtruerequiredfieldobjectrequiredFields
kind"field"requiredblockIdstringrequiredoccurrenceIndexintegerrequirednestingDepthintegerstoryIdstringfieldIdstringfalse
successfalserequiredfailureobjectrequiredFields
codestringrequiredmessagestringrequireddetailsunknownFailures
Pre-apply throws
TARGET_NOT_FOUNDINVALID_TARGETINVALID_INPUT
1 more codes
CAPABILITY_UNAVAILABLE
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