> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 |
| `target.story` | StoryLocator | no | StoryLocator |
| `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

```json theme={null}
{
  "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.selectionTarget.story` | StoryLocator | no | StoryLocator |
| `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.selectionTarget.story` | StoryLocator | no | StoryLocator |
| `resolution.target` | TextAddress \| BlockNodeAddress | no | One of: TextAddress, BlockNodeAddress |
| `success` | `false` | yes | Constant: `false` |

### Example response

```json theme={null}
{
  "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

> [accordion] Raw input schema
>
> ```json theme={null}
> {
>   "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"
>         }
>       ]
>     }
>   ]
> }
> ```

> [accordion] Raw output schema
>
> ```json theme={null}
> {
>   "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"
>     }
>   ]
> }
> ```

> [accordion] Raw success schema
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [accordion] Raw failure schema
>
> ```json theme={null}
> {
>   "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"
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.