insert

Insert content at a target position, or at the end of the document when target is omitted. Supports text (default), markdown, and html content types via the type field.

Alpha: Document API is currently alpha and subject to breaking changes.

Summary

Insert content at a target position, or at the end of the document when target is omitted. Supports text (default), markdown, and html content types via the type field.

• 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 a TextMutationReceipt with applied status; receipt reports NO_OP if the insertion point is invalid or content is empty.

Input fields

Field	Type	Required	Description
target	TextAddress	no	TextAddress
target.blockId	string	no
target.kind	"text"	no	Constant: "text"
target.range	Range	no	Range
target.range.end	integer	no
target.range.start	integer	no
type	enum	no	"text", "markdown", "html"
value	string	yes

Example request

{
  "target": {
    "blockId": "block-abc123",
    "kind": "text",
    "range": {
      "end": 10,
      "start": 0
    }
  },
  "type": "text",
  "value": "example"
}

Output fields

Variant 1 (resolution.requestedTarget.kind=“text”)

Field	Type	Required	Description
inserted	EntityAddress[]	no
removed	EntityAddress[]	no
resolution	TextMutationResolution	yes	TextMutationResolution
resolution.range	TextMutationRange	yes	TextMutationRange
resolution.range.from	integer	yes
resolution.range.to	integer	yes
resolution.requestedTarget	TextAddress	no	TextAddress
resolution.requestedTarget.blockId	string	no
resolution.requestedTarget.kind	"text"	no	Constant: "text"
resolution.requestedTarget.range	Range	no	Range
resolution.requestedTarget.range.end	integer	no
resolution.requestedTarget.range.start	integer	no
resolution.target	TextAddress	yes	TextAddress
resolution.target.blockId	string	yes
resolution.target.kind	"text"	yes	Constant: "text"
resolution.target.range	Range	yes	Range
resolution.target.range.end	integer	yes
resolution.target.range.start	integer	yes
resolution.text	string	yes
success	true	yes	Constant: true
updated	EntityAddress[]	no

Variant 2 (resolution.requestedTarget.kind=“text”)

Field	Type	Required	Description
failure	object	yes
failure.code	enum	yes	"INVALID_TARGET", "NO_OP", "CAPABILITY_UNAVAILABLE", "UNSUPPORTED_ENVIRONMENT"
failure.details	any	no
failure.message	string	yes
resolution	TextMutationResolution	yes	TextMutationResolution
resolution.range	TextMutationRange	yes	TextMutationRange
resolution.range.from	integer	yes
resolution.range.to	integer	yes
resolution.requestedTarget	TextAddress	no	TextAddress
resolution.requestedTarget.blockId	string	no
resolution.requestedTarget.kind	"text"	no	Constant: "text"
resolution.requestedTarget.range	Range	no	Range
resolution.requestedTarget.range.end	integer	no
resolution.requestedTarget.range.start	integer	no
resolution.target	TextAddress	yes	TextAddress
resolution.target.blockId	string	yes
resolution.target.kind	"text"	yes	Constant: "text"
resolution.target.range	Range	yes	Range
resolution.target.range.end	integer	yes
resolution.target.range.start	integer	yes
resolution.text	string	yes
success	false	yes	Constant: false

Example response

{
  "inserted": [
    {
      "entityId": "entity-789",
      "entityType": "comment",
      "kind": "entity"
    }
  ],
  "resolution": {
    "range": {
      "from": 0,
      "to": 10
    },
    "requestedTarget": {
      "blockId": "block-abc123",
      "kind": "text",
      "range": {
        "end": 10,
        "start": 0
      }
    },
    "target": {
      "blockId": "block-abc123",
      "kind": "text",
      "range": {
        "end": 10,
        "start": 0
      }
    },
    "text": "Hello, world."
  },
  "success": true,
  "updated": [
    {
      "entityId": "entity-789",
      "entityType": "comment",
      "kind": "entity"
    }
  ]
}

Pre-apply throws

• TARGET_NOT_FOUND
• CAPABILITY_UNAVAILABLE
• INVALID_TARGET

Non-applied failure codes

• INVALID_TARGET
• NO_OP
• CAPABILITY_UNAVAILABLE
• UNSUPPORTED_ENVIRONMENT

Raw schemas

Raw input schema

{
  "additionalProperties": false,
  "properties": {
    "target": {
      "$ref": "#/$defs/TextAddress"
    },
    "type": {
      "enum": [
        "text",
        "markdown",
        "html"
      ],
      "type": "string"
    },
    "value": {
      "type": "string"
    }
  },
  "required": [
    "value"
  ],
  "type": "object"
}

Raw output schema

{
  "oneOf": [
    {
      "$ref": "#/$defs/TextMutationSuccess"
    },
    {
      "additionalProperties": false,
      "properties": {
        "failure": {
          "additionalProperties": false,
          "properties": {
            "code": {
              "enum": [
                "INVALID_TARGET",
                "NO_OP",
                "CAPABILITY_UNAVAILABLE",
                "UNSUPPORTED_ENVIRONMENT"
              ]
            },
            "details": {},
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object"
        },
        "resolution": {
          "$ref": "#/$defs/TextMutationResolution"
        },
        "success": {
          "const": false
        }
      },
      "required": [
        "success",
        "failure",
        "resolution"
      ],
      "type": "object"
    }
  ]
}

Raw success schema

{
  "$ref": "#/$defs/TextMutationSuccess"
}

Raw failure schema

{
  "additionalProperties": false,
  "properties": {
    "failure": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "enum": [
            "INVALID_TARGET",
            "NO_OP",
            "CAPABILITY_UNAVAILABLE",
            "UNSUPPORTED_ENVIRONMENT"
          ]
        },
        "details": {},
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "resolution": {
      "$ref": "#/$defs/TextMutationResolution"
    },
    "success": {
      "const": false
    }
  },
  "required": [
    "success",
    "failure",
    "resolution"
  ],
  "type": "object"
}