Alpha: Document API is currently alpha and subject to breaking changes.
Summary
Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts an SDAddress, SelectionTarget, 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
| Field | Type | Required | Description |
|---|---|---|---|
ref | string | no | |
target | SelectionTarget | no | SelectionTarget |
target.end | SelectionPoint | no | SelectionPoint |
target.kind | "selection" | no | Constant: "selection" |
target.start | SelectionPoint | no | SelectionPoint |
text | string | yes |
Variant 2
| Field | Type | Required | Description | ||
|---|---|---|---|---|---|
content | object | yes | |||
nestingPolicy | object | no | |||
ref | string | no | |||
target | object \ | TextAddress \ | SelectionTarget | no | One of: object, TextAddress, SelectionTarget |
Example request
Copy
Ask AI
{
"target": {
"end": {
"blockId": "block-abc123",
"kind": "text",
"offset": 0
},
"kind": "selection",
"start": {
"blockId": "block-abc123",
"kind": "text",
"offset": 0
}
},
"text": "Hello, world."
}
Output fields
Variant 1 (resolution.selectionTarget.kind=“selection”)
| 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.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 | 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 (resolution.selectionTarget.kind=“selection”)
| 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.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.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 | 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
Copy
Ask AI
{
"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"
},
"selectionTarget": {
"end": {
"blockId": "block-abc123",
"kind": "text",
"offset": 0
},
"kind": "selection",
"start": {
"blockId": "block-abc123",
"kind": "text",
"offset": 0
}
},
"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_OPINVALID_NESTINGINVALID_PLACEMENTINVALID_PAYLOADCAPABILITY_UNSUPPORTEDADDRESS_STALEDUPLICATE_IDINVALID_CONTEXTRAW_MODE_REQUIREDPRESERVE_ONLY_VIOLATIONINVALID_INPUT
Raw schemas
Raw input schema
Raw input schema
Copy
Ask AI
{
"oneOf": [
{
"allOf": [
{
"$ref": "#/$defs/TargetLocator"
},
{
"additionalProperties": false,
"properties": {
"text": {
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
}
]
},
{
"allOf": [
{
"oneOf": [
{
"additionalProperties": false,
"properties": {
"target": {
"oneOf": [
{
"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"
},
{
"$ref": "#/$defs/TextAddress"
},
{
"$ref": "#/$defs/SelectionTarget"
}
]
}
},
"required": [
"target"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"ref": {
"type": "string"
}
},
"required": [
"ref"
],
"type": "object"
}
]
},
{
"additionalProperties": false,
"properties": {
"content": {
"type": "object"
},
"nestingPolicy": {
"type": "object"
},
"ref": {
"type": "string"
},
"target": {
"oneOf": [
{
"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"
},
{
"$ref": "#/$defs/TextAddress"
},
{
"$ref": "#/$defs/SelectionTarget"
}
]
}
},
"required": [
"content"
],
"type": "object"
}
]
}
]
}
Raw output schema
Raw output schema
Copy
Ask AI
{
"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"
},
"selectionTarget": {
"$ref": "#/$defs/SelectionTarget"
},
"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",
"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"
},
"selectionTarget": {
"$ref": "#/$defs/SelectionTarget"
},
"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
Copy
Ask AI
{
"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"
},
"selectionTarget": {
"$ref": "#/$defs/SelectionTarget"
},
"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
Copy
Ask AI
{
"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": {
"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"
},
"selectionTarget": {
"$ref": "#/$defs/SelectionTarget"
},
"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"
}