> ## 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.

# insert

> Insert content into the document. Two input shapes: text-based (value + type) inserts inline content at a SelectionTarget or ref position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target/ref is omitted, content appends at the end of the document. Text 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.

## Summary

Insert content into the document. Two input shapes: text-based (value + type) inserts inline content at a SelectionTarget or ref position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target/ref is omitted, content appends at the end of the document. Text 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 the inserted TextAddress for 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.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 |
| `type` | enum | no | `"text"`, `"markdown"`, `"html"` |
| `value` | string | yes | |

### Variant 1.2 (required: ref, value)

| Field | Type | Required | Description |
| - | - | - | - |
| `in` | StoryLocator | no | StoryLocator |
| `ref` | string | yes | |
| `type` | enum | no | `"text"`, `"markdown"`, `"html"` |
| `value` | string | yes | |

### Variant 1.3 (required: value)

| Field | Type | Required | Description |
| - | - | - | - |
| `in` | StoryLocator | no | StoryLocator |
| `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\[] |
| `in` | StoryLocator | no | StoryLocator |
| `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"` |
| `target.story` | StoryLocator | no | StoryLocator |

### Example request

```json theme={null}
{
  "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.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"`, `"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.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": 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`
* `STORY_NOT_FOUND`
* `STORY_MISMATCH`
* `STORY_NOT_SUPPORTED`
* `CROSS_STORY_PLAN`
* `MATERIALIZATION_FAILED`

## 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

> [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}}."
>             },
>             "type": {
>               "description": "Content format: 'text' (default), 'markdown', or 'html'.",
>               "enum": [
>                 "text",
>                 "markdown",
>                 "html"
>               ],
>               "type": "string"
>             },
>             "value": {
>               "description": "Text content to insert.",
>               "type": "string"
>             }
>           },
>           "required": [
>             "target",
>             "value"
>           ],
>           "type": "object"
>         },
>         {
>           "additionalProperties": false,
>           "properties": {
>             "in": {
>               "$ref": "#/$defs/StoryLocator"
>             },
>             "ref": {
>               "description": "Handle ref from superdoc_search result (pass handle.ref value directly). Preferred over building a target object.",
>               "type": "string"
>             },
>             "type": {
>               "description": "Content format: 'text' (default), 'markdown', or 'html'.",
>               "enum": [
>                 "text",
>                 "markdown",
>                 "html"
>               ],
>               "type": "string"
>             },
>             "value": {
>               "description": "Text content to insert.",
>               "type": "string"
>             }
>           },
>           "required": [
>             "ref",
>             "value"
>           ],
>           "type": "object"
>         },
>         {
>           "additionalProperties": false,
>           "properties": {
>             "in": {
>               "$ref": "#/$defs/StoryLocator"
>             },
>             "type": {
>               "description": "Content format: 'text' (default), 'markdown', or 'html'.",
>               "enum": [
>                 "text",
>                 "markdown",
>                 "html"
>               ],
>               "type": "string"
>             },
>             "value": {
>               "description": "Text content to insert.",
>               "type": "string"
>             }
>           },
>           "required": [
>             "value"
>           ],
>           "type": "object"
>         }
>       ]
>     },
>     {
>       "additionalProperties": false,
>       "properties": {
>         "content": {
>           "description": "Document fragment to insert (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"
>         },
>         "placement": {
>           "description": "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'.",
>           "enum": [
>             "before",
>             "after",
>             "insideStart",
>             "insideEnd"
>           ]
>         },
>         "target": {
>           "$ref": "#/$defs/BlockNodeAddress",
>           "description": "Block address for structural insertion: {kind:'block', nodeType:'...', nodeId:'...'}."
>         }
>       },
>       "required": [
>         "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",
>                 "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"
>     }
>   ]
> }
> ```

> [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",
>             "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"
> }
> ```


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