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. Accepts two input shapes: legacy string-based (value + type) or structural SDFragment (content). Supports text (default), markdown, and html content types via thetype field in legacy mode. Structural mode accepts an SDFragment with typed nodes (paragraphs, tables, images, etc.).
- 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 (success=true)
| Field | Type | Required | Description | |
|---|---|---|---|---|
evaluatedRevision | object | no | ||
evaluatedRevision.after | string | no | ||
evaluatedRevision.before | string | no | ||
resolution | object | no | ||
resolution.requestedTarget | object | no | ||
resolution.requestedTarget.anchor | object | no | ||
resolution.requestedTarget.anchor.end | object | no | ||
resolution.requestedTarget.anchor.end.blockId | string | no | ||
resolution.requestedTarget.anchor.end.offset | integer | no | ||
resolution.requestedTarget.anchor.start | object | no | ||
resolution.requestedTarget.anchor.start.blockId | string | no | ||
resolution.requestedTarget.anchor.start.offset | integer | no | ||
resolution.requestedTarget.evaluatedRevision | string | no | ||
resolution.requestedTarget.kind | enum | no | "content", "inline", "annotation", "section" | |
resolution.requestedTarget.nodeId | string | no | ||
resolution.requestedTarget.path | string \ | integer[] | no | |
resolution.requestedTarget.stability | enum | no | "stable", "ephemeral" | |
resolution.target | object | no | ||
resolution.target.anchor | object | no | ||
resolution.target.anchor.end | object | no | ||
resolution.target.anchor.end.blockId | string | no | ||
resolution.target.anchor.end.offset | integer | no | ||
resolution.target.anchor.start | object | no | ||
resolution.target.anchor.start.blockId | string | no | ||
resolution.target.anchor.start.offset | integer | no | ||
resolution.target.evaluatedRevision | string | no | ||
resolution.target.kind | enum | no | "content", "inline", "annotation", "section" | |
resolution.target.nodeId | string | no | ||
resolution.target.path | string \ | integer[] | no | |
resolution.target.stability | enum | no | "stable", "ephemeral" | |
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.requestedTarget | object | no | ||
resolution.requestedTarget.anchor | object | no | ||
resolution.requestedTarget.anchor.end | object | no | ||
resolution.requestedTarget.anchor.end.blockId | string | no | ||
resolution.requestedTarget.anchor.end.offset | integer | no | ||
resolution.requestedTarget.anchor.start | object | no | ||
resolution.requestedTarget.anchor.start.blockId | string | no | ||
resolution.requestedTarget.anchor.start.offset | integer | no | ||
resolution.requestedTarget.evaluatedRevision | string | no | ||
resolution.requestedTarget.kind | enum | no | "content", "inline", "annotation", "section" | |
resolution.requestedTarget.nodeId | string | no | ||
resolution.requestedTarget.path | string \ | integer[] | no | |
resolution.requestedTarget.stability | enum | no | "stable", "ephemeral" | |
resolution.target | object | no | ||
resolution.target.anchor | object | no | ||
resolution.target.anchor.end | object | no | ||
resolution.target.anchor.end.blockId | string | no | ||
resolution.target.anchor.end.offset | integer | no | ||
resolution.target.anchor.start | object | no | ||
resolution.target.anchor.start.blockId | string | no | ||
resolution.target.anchor.start.offset | integer | no | ||
resolution.target.evaluatedRevision | string | no | ||
resolution.target.kind | enum | no | "content", "inline", "annotation", "section" | |
resolution.target.nodeId | string | no | ||
resolution.target.path | string \ | integer[] | no | |
resolution.target.stability | enum | no | "stable", "ephemeral" | |
success | false | yes | Constant: false |
Example response
{
"evaluatedRevision": {
"after": "example",
"before": "example"
},
"resolution": {
"requestedTarget": {
"anchor": {
"end": {
"blockId": "block-abc123",
"offset": 0
},
"start": {
"blockId": "block-abc123",
"offset": 0
}
},
"kind": "content",
"nodeId": "node-def456",
"stability": "stable"
},
"target": {
"anchor": {
"end": {
"blockId": "block-abc123",
"offset": 0
},
"start": {
"blockId": "block-abc123",
"offset": 0
}
},
"kind": "content",
"nodeId": "node-def456",
"stability": "stable"
}
},
"success": true
}
Pre-apply throws
TARGET_NOT_FOUNDCAPABILITY_UNAVAILABLEINVALID_TARGETINVALID_INPUTADDRESS_STALEDUPLICATE_IDRAW_MODE_REQUIREDPRESERVE_ONLY_VIOLATIONCAPABILITY_UNSUPPORTED
Non-applied failure codes
INVALID_TARGETNO_OPCAPABILITY_UNAVAILABLEUNSUPPORTED_ENVIRONMENTINVALID_NESTINGINVALID_PLACEMENTINVALID_PAYLOADCAPABILITY_UNSUPPORTEDADDRESS_STALEDUPLICATE_IDINVALID_CONTEXTRAW_MODE_REQUIREDPRESERVE_ONLY_VIOLATIONINVALID_INPUT
Raw schemas
Raw input schema
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
Raw output schema
{
"oneOf": [
{
"additionalProperties": false,
"properties": {
"evaluatedRevision": {
"additionalProperties": false,
"properties": {
"after": {
"type": "string"
},
"before": {
"type": "string"
}
},
"required": [
"before",
"after"
],
"type": "object"
},
"resolution": {
"additionalProperties": false,
"properties": {
"requestedTarget": {
"additionalProperties": false,
"properties": {
"anchor": {
"additionalProperties": false,
"properties": {
"end": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
},
"start": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
}
},
"type": "object"
},
"evaluatedRevision": {
"type": "string"
},
"kind": {
"enum": [
"content",
"inline",
"annotation",
"section"
]
},
"nodeId": {
"type": "string"
},
"path": {
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
"stability": {
"enum": [
"stable",
"ephemeral"
]
}
},
"required": [
"kind",
"stability"
],
"type": "object"
},
"target": {
"additionalProperties": false,
"properties": {
"anchor": {
"additionalProperties": false,
"properties": {
"end": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
},
"start": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
}
},
"type": "object"
},
"evaluatedRevision": {
"type": "string"
},
"kind": {
"enum": [
"content",
"inline",
"annotation",
"section"
]
},
"nodeId": {
"type": "string"
},
"path": {
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
"stability": {
"enum": [
"stable",
"ephemeral"
]
}
},
"required": [
"kind",
"stability"
],
"type": "object"
}
},
"required": [
"target"
],
"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": {
"requestedTarget": {
"additionalProperties": false,
"properties": {
"anchor": {
"additionalProperties": false,
"properties": {
"end": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
},
"start": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
}
},
"type": "object"
},
"evaluatedRevision": {
"type": "string"
},
"kind": {
"enum": [
"content",
"inline",
"annotation",
"section"
]
},
"nodeId": {
"type": "string"
},
"path": {
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
"stability": {
"enum": [
"stable",
"ephemeral"
]
}
},
"required": [
"kind",
"stability"
],
"type": "object"
},
"target": {
"additionalProperties": false,
"properties": {
"anchor": {
"additionalProperties": false,
"properties": {
"end": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
},
"start": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
}
},
"type": "object"
},
"evaluatedRevision": {
"type": "string"
},
"kind": {
"enum": [
"content",
"inline",
"annotation",
"section"
]
},
"nodeId": {
"type": "string"
},
"path": {
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
"stability": {
"enum": [
"stable",
"ephemeral"
]
}
},
"required": [
"kind",
"stability"
],
"type": "object"
}
},
"required": [
"target"
],
"type": "object"
},
"success": {
"const": false
}
},
"required": [
"success",
"failure"
],
"type": "object"
}
]
}
Raw success schema
Raw success schema
{
"additionalProperties": false,
"properties": {
"evaluatedRevision": {
"additionalProperties": false,
"properties": {
"after": {
"type": "string"
},
"before": {
"type": "string"
}
},
"required": [
"before",
"after"
],
"type": "object"
},
"resolution": {
"additionalProperties": false,
"properties": {
"requestedTarget": {
"additionalProperties": false,
"properties": {
"anchor": {
"additionalProperties": false,
"properties": {
"end": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
},
"start": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
}
},
"type": "object"
},
"evaluatedRevision": {
"type": "string"
},
"kind": {
"enum": [
"content",
"inline",
"annotation",
"section"
]
},
"nodeId": {
"type": "string"
},
"path": {
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
"stability": {
"enum": [
"stable",
"ephemeral"
]
}
},
"required": [
"kind",
"stability"
],
"type": "object"
},
"target": {
"additionalProperties": false,
"properties": {
"anchor": {
"additionalProperties": false,
"properties": {
"end": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
},
"start": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
}
},
"type": "object"
},
"evaluatedRevision": {
"type": "string"
},
"kind": {
"enum": [
"content",
"inline",
"annotation",
"section"
]
},
"nodeId": {
"type": "string"
},
"path": {
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
"stability": {
"enum": [
"stable",
"ephemeral"
]
}
},
"required": [
"kind",
"stability"
],
"type": "object"
}
},
"required": [
"target"
],
"type": "object"
},
"success": {
"const": true
}
},
"required": [
"success"
],
"type": "object"
}
Raw failure schema
Raw failure schema
{
"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": {
"requestedTarget": {
"additionalProperties": false,
"properties": {
"anchor": {
"additionalProperties": false,
"properties": {
"end": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
},
"start": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
}
},
"type": "object"
},
"evaluatedRevision": {
"type": "string"
},
"kind": {
"enum": [
"content",
"inline",
"annotation",
"section"
]
},
"nodeId": {
"type": "string"
},
"path": {
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
"stability": {
"enum": [
"stable",
"ephemeral"
]
}
},
"required": [
"kind",
"stability"
],
"type": "object"
},
"target": {
"additionalProperties": false,
"properties": {
"anchor": {
"additionalProperties": false,
"properties": {
"end": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
},
"start": {
"additionalProperties": false,
"properties": {
"blockId": {
"type": "string"
},
"offset": {
"type": "integer"
}
},
"required": [
"blockId",
"offset"
],
"type": "object"
}
},
"type": "object"
},
"evaluatedRevision": {
"type": "string"
},
"kind": {
"enum": [
"content",
"inline",
"annotation",
"section"
]
},
"nodeId": {
"type": "string"
},
"path": {
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array"
},
"stability": {
"enum": [
"stable",
"ephemeral"
]
}
},
"required": [
"kind",
"stability"
],
"type": "object"
}
},
"required": [
"target"
],
"type": "object"
},
"success": {
"const": false
}
},
"required": [
"success",
"failure"
],
"type": "object"
}