insert

Alpha: Document API is currently alpha and subject to breaking changes.

Summary

Insert content into the document. Two input shapes: legacy string-based (value + type) inserts inline content at a text position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target is omitted, content appends at the end of the document. Legacy mode supports text (default), markdown, and html content types via the type field. Structural mode uses placement (before/after/insideStart/insideEnd) to position relative to the target block.

Operation ID: insert
API member path: editor.doc.insert(...)
Mutates document: yes
Idempotency: non-idempotent
Supports tracked mode: yes
Supports dry run: yes
Deterministic target resolution: yes

Expected result

Returns an SDMutationReceipt with applied status; resolution reports a TextAddress for legacy text insertion or a BlockNodeAddress for structural insertion. Receipt reports NO_OP if the insertion point is invalid or content is empty.

Input fields

Variant 1 (target.kind=“text”)

Field	Type	Required	Description
`target`	TextAddress	no	TextAddress
`target.blockId`	string	no
`target.kind`	`"text"`	no	Constant: `"text"`
`target.range`	Range	no	Range
`target.range.end`	integer	no
`target.range.start`	integer	no
`type`	enum	no	`"text"`, `"markdown"`, `"html"`
`value`	string	yes

Variant 2 (target.kind=“block”)

Field	Type	Required	Description
`content`	object \	object[]	yes	One of: object, object[]
`nestingPolicy`	object	no
`nestingPolicy.tables`	enum	no	`"forbid"`, `"allow"`
`placement`	enum	no	`"before"`, `"after"`, `"insideStart"`, `"insideEnd"`
`target`	BlockNodeAddress	no	BlockNodeAddress
`target.kind`	`"block"`	no	Constant: `"block"`
`target.nodeId`	string	no
`target.nodeType`	enum	no	`"paragraph"`, `"heading"`, `"listItem"`, `"table"`, `"tableRow"`, `"tableCell"`, `"tableOfContents"`, `"image"`, `"sdt"`

Example request

{
  "content": {
    "content": [
      {
        "text": "example",
        "type": "text"
      }
    ],
    "type": "paragraph"
  },
  "placement": "after",
  "target": {
    "kind": "block",
    "nodeId": "node-def456",
    "nodeType": "paragraph"
  }
}

Output fields

Variant 1 (success=true)

Field	Type	Required	Description
`evaluatedRevision`	object	no
`evaluatedRevision.after`	string	no
`evaluatedRevision.before`	string	no
`resolution`	object	no
`resolution.range`	TextMutationRange	no	TextMutationRange
`resolution.range.from`	integer	no
`resolution.range.to`	integer	no
`resolution.selectionTarget`	SelectionTarget	no	SelectionTarget
`resolution.selectionTarget.end`	SelectionPoint	no	SelectionPoint
`resolution.selectionTarget.kind`	`"selection"`	no	Constant: `"selection"`
`resolution.selectionTarget.start`	SelectionPoint	no	SelectionPoint
`resolution.target`	TextAddress \	BlockNodeAddress	no	One of: TextAddress, BlockNodeAddress
`success`	`true`	yes	Constant: `true`

Variant 2 (success=false)

Field	Type	Required	Description
`evaluatedRevision`	object	no
`evaluatedRevision.after`	string	no
`evaluatedRevision.before`	string	no
`failure`	object	yes
`failure.code`	enum	yes	`"INVALID_TARGET"`, `"NO_OP"`, `"CAPABILITY_UNAVAILABLE"`, `"UNSUPPORTED_ENVIRONMENT"`, `"INVALID_NESTING"`, `"INVALID_PLACEMENT"`, `"INVALID_PAYLOAD"`, `"CAPABILITY_UNSUPPORTED"`, `"ADDRESS_STALE"`, `"DUPLICATE_ID"`, `"INVALID_CONTEXT"`, `"RAW_MODE_REQUIRED"`, `"PRESERVE_ONLY_VIOLATION"`, `"INVALID_INPUT"`
`failure.details`	any	no
`failure.message`	string	yes
`resolution`	object	no
`resolution.range`	TextMutationRange	no	TextMutationRange
`resolution.range.from`	integer	no
`resolution.range.to`	integer	no
`resolution.selectionTarget`	SelectionTarget	no	SelectionTarget
`resolution.selectionTarget.end`	SelectionPoint	no	SelectionPoint
`resolution.selectionTarget.kind`	`"selection"`	no	Constant: `"selection"`
`resolution.selectionTarget.start`	SelectionPoint	no	SelectionPoint
`resolution.target`	TextAddress \	BlockNodeAddress	no	One of: TextAddress, BlockNodeAddress
`success`	`false`	yes	Constant: `false`

Example response

{
  "evaluatedRevision": {
    "after": "rev-002",
    "before": "rev-001"
  },
  "resolution": {
    "range": {
      "from": 42,
      "to": 42
    },
    "target": {
      "kind": "block",
      "nodeId": "node-def456",
      "nodeType": "paragraph"
    }
  },
  "success": true
}

Pre-apply throws

TARGET_NOT_FOUND
CAPABILITY_UNAVAILABLE
INVALID_TARGET
INVALID_INPUT
ADDRESS_STALE
DUPLICATE_ID
RAW_MODE_REQUIRED
PRESERVE_ONLY_VIOLATION
CAPABILITY_UNSUPPORTED

Non-applied failure codes

INVALID_TARGET
NO_OP
CAPABILITY_UNAVAILABLE
UNSUPPORTED_ENVIRONMENT
INVALID_NESTING
INVALID_PLACEMENT
INVALID_PAYLOAD
CAPABILITY_UNSUPPORTED
ADDRESS_STALE
DUPLICATE_ID
INVALID_CONTEXT
RAW_MODE_REQUIRED
PRESERVE_ONLY_VIOLATION
INVALID_INPUT

Raw schemas

Raw input schema

{
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "target": {
          "$ref": "#/$defs/TextAddress"
        },
        "type": {
          "enum": [
            "text",
            "markdown",
            "html"
          ],
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      },
      "required": [
        "value"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "content": {
          "oneOf": [
            {
              "type": "object"
            },
            {
              "items": {
                "type": "object"
              },
              "type": "array"
            }
          ]
        },
        "nestingPolicy": {
          "additionalProperties": false,
          "properties": {
            "tables": {
              "enum": [
                "forbid",
                "allow"
              ]
            }
          },
          "type": "object"
        },
        "placement": {
          "enum": [
            "before",
            "after",
            "insideStart",
            "insideEnd"
          ]
        },
        "target": {
          "$ref": "#/$defs/BlockNodeAddress"
        }
      },
      "required": [
        "content"
      ],
      "type": "object"
    }
  ]
}

Raw output schema

{
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "evaluatedRevision": {
          "additionalProperties": false,
          "properties": {
            "after": {
              "type": "string"
            },
            "before": {
              "type": "string"
            }
          },
          "required": [
            "before",
            "after"
          ],
          "type": "object"
        },
        "resolution": {
          "additionalProperties": false,
          "properties": {
            "range": {
              "$ref": "#/$defs/TextMutationRange"
            },
            "selectionTarget": {
              "$ref": "#/$defs/SelectionTarget"
            },
            "target": {
              "oneOf": [
                {
                  "$ref": "#/$defs/TextAddress"
                },
                {
                  "$ref": "#/$defs/BlockNodeAddress"
                }
              ]
            }
          },
          "required": [
            "target",
            "range"
          ],
          "type": "object"
        },
        "success": {
          "const": true
        }
      },
      "required": [
        "success"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "evaluatedRevision": {
          "additionalProperties": false,
          "properties": {
            "after": {
              "type": "string"
            },
            "before": {
              "type": "string"
            }
          },
          "required": [
            "before",
            "after"
          ],
          "type": "object"
        },
        "failure": {
          "additionalProperties": false,
          "properties": {
            "code": {
              "enum": [
                "INVALID_TARGET",
                "NO_OP",
                "CAPABILITY_UNAVAILABLE",
                "UNSUPPORTED_ENVIRONMENT",
                "INVALID_NESTING",
                "INVALID_PLACEMENT",
                "INVALID_PAYLOAD",
                "CAPABILITY_UNSUPPORTED",
                "ADDRESS_STALE",
                "DUPLICATE_ID",
                "INVALID_CONTEXT",
                "RAW_MODE_REQUIRED",
                "PRESERVE_ONLY_VIOLATION",
                "INVALID_INPUT"
              ]
            },
            "details": {},
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object"
        },
        "resolution": {
          "additionalProperties": false,
          "properties": {
            "range": {
              "$ref": "#/$defs/TextMutationRange"
            },
            "selectionTarget": {
              "$ref": "#/$defs/SelectionTarget"
            },
            "target": {
              "oneOf": [
                {
                  "$ref": "#/$defs/TextAddress"
                },
                {
                  "$ref": "#/$defs/BlockNodeAddress"
                }
              ]
            }
          },
          "required": [
            "target",
            "range"
          ],
          "type": "object"
        },
        "success": {
          "const": false
        }
      },
      "required": [
        "success",
        "failure"
      ],
      "type": "object"
    }
  ]
}

Raw success schema

{
  "additionalProperties": false,
  "properties": {
    "evaluatedRevision": {
      "additionalProperties": false,
      "properties": {
        "after": {
          "type": "string"
        },
        "before": {
          "type": "string"
        }
      },
      "required": [
        "before",
        "after"
      ],
      "type": "object"
    },
    "resolution": {
      "additionalProperties": false,
      "properties": {
        "range": {
          "$ref": "#/$defs/TextMutationRange"
        },
        "selectionTarget": {
          "$ref": "#/$defs/SelectionTarget"
        },
        "target": {
          "oneOf": [
            {
              "$ref": "#/$defs/TextAddress"
            },
            {
              "$ref": "#/$defs/BlockNodeAddress"
            }
          ]
        }
      },
      "required": [
        "target",
        "range"
      ],
      "type": "object"
    },
    "success": {
      "const": true
    }
  },
  "required": [
    "success"
  ],
  "type": "object"
}

Raw failure schema

{
  "additionalProperties": false,
  "properties": {
    "evaluatedRevision": {
      "additionalProperties": false,
      "properties": {
        "after": {
          "type": "string"
        },
        "before": {
          "type": "string"
        }
      },
      "required": [
        "before",
        "after"
      ],
      "type": "object"
    },
    "failure": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "enum": [
            "INVALID_TARGET",
            "NO_OP",
            "CAPABILITY_UNAVAILABLE",
            "UNSUPPORTED_ENVIRONMENT",
            "INVALID_NESTING",
            "INVALID_PLACEMENT",
            "INVALID_PAYLOAD",
            "CAPABILITY_UNSUPPORTED",
            "ADDRESS_STALE",
            "DUPLICATE_ID",
            "INVALID_CONTEXT",
            "RAW_MODE_REQUIRED",
            "PRESERVE_ONLY_VIOLATION",
            "INVALID_INPUT"
          ]
        },
        "details": {},
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "resolution": {
      "additionalProperties": false,
      "properties": {
        "range": {
          "$ref": "#/$defs/TextMutationRange"
        },
        "selectionTarget": {
          "$ref": "#/$defs/SelectionTarget"
        },
        "target": {
          "oneOf": [
            {
              "$ref": "#/$defs/TextAddress"
            },
            {
              "$ref": "#/$defs/BlockNodeAddress"
            }
          ]
        }
      },
      "required": [
        "target",
        "range"
      ],
      "type": "object"
    },
    "success": {
      "const": false
    }
  },
  "required": [
    "success",
    "failure"
  ],
  "type": "object"
}

Getting Started

Core

Document Engine

Modules

Extensions

Solutions

Guides

Resources

Summary

Expected result

Input fields

Variant 1 (target.kind=“text”)

Variant 2 (target.kind=“block”)

Example request

Output fields

Variant 1 (success=true)

Variant 2 (success=false)

Example response

Pre-apply throws

Non-applied failure codes

Raw schemas

Getting Started

Core

Document Engine

Modules

Extensions

Solutions

Guides

Resources

​Summary

​Expected result

​Input fields

​Variant 1 (target.kind=“text”)

​Variant 2 (target.kind=“block”)

​Example request

​Output fields

​Variant 1 (success=true)

​Variant 2 (success=false)

​Example response

​Pre-apply throws

​Non-applied failure codes

​Raw schemas

Summary

Expected result

Input fields

Variant 1 (target.kind=“text”)

Variant 2 (target.kind=“block”)

Example request

Output fields

Variant 1 (success=true)

Variant 2 (success=false)

Example response

Pre-apply throws

Non-applied failure codes

Raw schemas