> ## 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.
# 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 |
| `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"` |
### 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.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
```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
```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"
}
]
}
```
```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"
}
]
}
```
```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",
"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"
}
```