replace

Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content.

Summary

Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content.

• Operation ID: replace
• API member path: editor.doc.replace(...)
• Mutates document: yes
• Idempotency: conditional
• Supports tracked mode: yes
• Supports dry run: yes
• Deterministic target resolution: yes

Expected result

Returns an SDMutationReceipt with applied status; receipt reports NO_OP if the target range already contains identical content.

Input fields

Variant 1.1 (target.kind=“selection”)

Field	Type	Required	Description
in	StoryLocator	no	StoryLocator
target	SelectionTarget	yes	SelectionTarget
target.end	SelectionPoint	yes	SelectionPoint
target.kind	"selection"	yes	Constant: "selection"
target.start	SelectionPoint	yes	SelectionPoint
text	string	yes

Variant 1.2 (required: ref, text)

Field	Type	Required	Description
in	StoryLocator	no	StoryLocator
ref	string	yes
text	string	yes

Variant 2.1 (required: target, content)

Field	Type	Required	Description
content	object | object[]	yes	One of: object, object[]
in	StoryLocator	no	StoryLocator
nestingPolicy	object	no
nestingPolicy.tables	enum	no	"forbid", "allow"
target	BlockNodeAddress | SelectionTarget	yes	One of: BlockNodeAddress, SelectionTarget

Variant 2.2 (required: ref, content)

Field	Type	Required	Description
content	object | object[]	yes	One of: object, object[]
in	StoryLocator	no	StoryLocator
nestingPolicy	object	no
nestingPolicy.tables	enum	no	"forbid", "allow"
ref	string	yes

Example request

{
  "target": {
    "end": {
      "blockId": "block-abc123",
      "kind": "text",
      "offset": 12
    },
    "kind": "selection",
    "start": {
      "blockId": "block-abc123",
      "kind": "text",
      "offset": 0
    }
  },
  "text": "Hello, world."
}

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", "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": 0,
      "to": 12
    },
    "target": {
      "blockId": "block-abc123",
      "kind": "text",
      "range": {
        "end": 12,
        "start": 0
      }
    }
  },
  "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
• STORY_NOT_FOUND
• STORY_MISMATCH
• STORY_NOT_SUPPORTED
• CROSS_STORY_PLAN
• MATERIALIZATION_FAILED

Non-applied failure codes

• INVALID_TARGET
• NO_OP
• 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": [
    {
      "oneOf": [
        {
          "additionalProperties": false,
          "properties": {
            "in": {
              "$ref": "#/$defs/StoryLocator"
            },
            "target": {
              "$ref": "#/$defs/SelectionTarget",
              "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle."
            },
            "text": {
              "description": "Replacement text content.",
              "type": "string"
            }
          },
          "required": [
            "target",
            "text"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "in": {
              "$ref": "#/$defs/StoryLocator"
            },
            "ref": {
              "description": "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting.",
              "type": "string"
            },
            "text": {
              "description": "Replacement text content.",
              "type": "string"
            }
          },
          "required": [
            "ref",
            "text"
          ],
          "type": "object"
        }
      ]
    },
    {
      "oneOf": [
        {
          "additionalProperties": false,
          "properties": {
            "content": {
              "description": "Document fragment to replace with (structured content).",
              "oneOf": [
                {
                  "type": "object"
                },
                {
                  "items": {
                    "type": "object"
                  },
                  "type": "array"
                }
              ]
            },
            "in": {
              "$ref": "#/$defs/StoryLocator"
            },
            "nestingPolicy": {
              "additionalProperties": false,
              "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables.",
              "properties": {
                "tables": {
                  "enum": [
                    "forbid",
                    "allow"
                  ]
                }
              },
              "type": "object"
            },
            "target": {
              "description": "Target block or selection to replace.",
              "oneOf": [
                {
                  "$ref": "#/$defs/BlockNodeAddress"
                },
                {
                  "$ref": "#/$defs/SelectionTarget"
                }
              ]
            }
          },
          "required": [
            "target",
            "content"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "content": {
              "description": "Document fragment to replace with (structured content).",
              "oneOf": [
                {
                  "type": "object"
                },
                {
                  "items": {
                    "type": "object"
                  },
                  "type": "array"
                }
              ]
            },
            "in": {
              "$ref": "#/$defs/StoryLocator"
            },
            "nestingPolicy": {
              "additionalProperties": false,
              "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables.",
              "properties": {
                "tables": {
                  "enum": [
                    "forbid",
                    "allow"
                  ]
                }
              },
              "type": "object"
            },
            "ref": {
              "description": "Reference handle from a previous search result.",
              "type": "string"
            }
          },
          "required": [
            "ref",
            "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",
                "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",
            "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"
}