Summary
Insert a new list item before or after an existing list item. The new item inherits the target list context.- Operation ID:
lists.insert - API member path:
editor.doc.lists.insert(...) - Mutates document:
yes - Idempotency:
non-idempotent - Supports tracked mode:
yes - Supports dry run:
yes - Deterministic target resolution:
yes
Expected result
Returns a ListsInsertResult with the new list item address and block ID.Input fields
| Field | Type | Required | Description |
|---|---|---|---|
position | enum | yes | "before", "after" |
target | ListItemAddress | yes | ListItemAddress |
target.kind | "block" | yes | Constant: "block" |
target.nodeId | string | yes | |
target.nodeType | "listItem" | yes | Constant: "listItem" |
target.story | StoryLocator | no | StoryLocator |
text | string | no |
Example request
{
"position": "before",
"target": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "listItem",
"story": {
"kind": "story",
"storyType": "body"
}
},
"text": "Hello, world."
}
Output fields
Variant 1 (success=true)
| Field | Type | Required | Description |
|---|---|---|---|
insertionPoint | TextAddress | yes | TextAddress |
insertionPoint.blockId | string | yes | |
insertionPoint.kind | "text" | yes | Constant: "text" |
insertionPoint.range | Range | yes | Range |
insertionPoint.range.end | integer | yes | |
insertionPoint.range.start | integer | yes | |
insertionPoint.story | StoryLocator | no | StoryLocator |
item | ListItemAddress | yes | ListItemAddress |
item.kind | "block" | yes | Constant: "block" |
item.nodeId | string | yes | |
item.nodeType | "listItem" | yes | Constant: "listItem" |
item.story | StoryLocator | no | StoryLocator |
success | true | yes | Constant: true |
trackedChangeRefs | TrackedChangeAddress[] | no |
Variant 2 (success=false)
| Field | Type | Required | Description |
|---|---|---|---|
failure | object | yes | |
failure.code | enum | yes | "INVALID_TARGET" |
failure.details | any | no | |
failure.message | string | yes | |
success | false | yes | Constant: false |
Example response
{
"insertionPoint": {
"blockId": "block-abc123",
"kind": "text",
"range": {
"end": 10,
"start": 0
},
"story": {
"kind": "story",
"storyType": "body"
}
},
"item": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "listItem",
"story": {
"kind": "story",
"storyType": "body"
}
},
"success": true,
"trackedChangeRefs": [
{
"entityId": "entity-789",
"entityType": "trackedChange",
"kind": "entity",
"story": {
"kind": "story",
"storyType": "body"
}
}
]
}
Pre-apply throws
TARGET_NOT_FOUNDCAPABILITY_UNAVAILABLEINVALID_TARGET
Non-applied failure codes
INVALID_TARGET
Raw schemas
Raw input schema
Raw input schema
{
"additionalProperties": false,
"properties": {
"position": {
"description": "Required. Insert position relative to target: 'before' or 'after'.",
"enum": [
"before",
"after"
]
},
"target": {
"$ref": "#/$defs/ListItemAddress",
"description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:'<id>'}."
},
"text": {
"description": "Text content for the new list item.",
"type": "string"
}
},
"required": [
"target",
"position"
],
"type": "object"
}
Raw output schema
Raw output schema
{
"oneOf": [
{
"additionalProperties": false,
"properties": {
"insertionPoint": {
"$ref": "#/$defs/TextAddress"
},
"item": {
"$ref": "#/$defs/ListItemAddress"
},
"success": {
"const": true
},
"trackedChangeRefs": {
"items": {
"$ref": "#/$defs/TrackedChangeAddress"
},
"type": "array"
}
},
"required": [
"success",
"item",
"insertionPoint"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"failure": {
"additionalProperties": false,
"properties": {
"code": {
"enum": [
"INVALID_TARGET"
]
},
"details": {},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"success": {
"const": false
}
},
"required": [
"success",
"failure"
],
"type": "object"
}
]
}
Raw success schema
Raw success schema
{
"additionalProperties": false,
"properties": {
"insertionPoint": {
"$ref": "#/$defs/TextAddress"
},
"item": {
"$ref": "#/$defs/ListItemAddress"
},
"success": {
"const": true
},
"trackedChangeRefs": {
"items": {
"$ref": "#/$defs/TrackedChangeAddress"
},
"type": "array"
}
},
"required": [
"success",
"item",
"insertionPoint"
],
"type": "object"
}
Raw failure schema
Raw failure schema
{
"additionalProperties": false,
"properties": {
"failure": {
"additionalProperties": false,
"properties": {
"code": {
"enum": [
"INVALID_TARGET"
]
},
"details": {},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"success": {
"const": false
}
},
"required": [
"success",
"failure"
],
"type": "object"
}