> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-caio-pizzol-docs-ai-core-preset.mintlify.site/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 |
| `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.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
```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
```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"
}
]
}
]
}
```
```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"
}
]
}
```
```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"
}
```
```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"
}
```