Summary
Create a new list from one or more paragraphs. Supports optional preset or style for new sequences. When sequence.mode is “continuePrevious”, preset and style are not allowed: the new items inherit formatting from the previous sequence.- Operation ID:
lists.create - API member path:
editor.doc.lists.create(...) - Mutates document:
yes - Idempotency:
non-idempotent - Supports tracked mode:
no - Supports dry run:
yes - Deterministic target resolution:
yes
Expected result
Returns a ListsCreateResult with the new listId and the first item address.Input fields
No fields.Example request
{
"at": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "paragraph"
},
"mode": "empty",
"target": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "paragraph"
}
}
Output fields
Variant 1 (success=true)
| Field | Type | Required | Description |
|---|---|---|---|
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 |
listId | string | yes | |
success | true | yes | Constant: true |
Variant 2 (success=false)
| Field | Type | Required | Description |
|---|---|---|---|
failure | object | yes | |
failure.code | enum | yes | "INVALID_TARGET", "LEVEL_OUT_OF_RANGE", "INVALID_INPUT", "NO_COMPATIBLE_PREVIOUS" |
failure.details | any | no | |
failure.message | string | yes | |
success | false | yes | Constant: false |
Example response
{
"item": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "listItem",
"story": {
"kind": "story",
"storyType": "body"
}
},
"listId": "example",
"success": true
}
Pre-apply throws
TARGET_NOT_FOUNDCAPABILITY_UNAVAILABLEINVALID_TARGETINVALID_INPUT
Non-applied failure codes
INVALID_TARGETLEVEL_OUT_OF_RANGEINVALID_INPUTNO_COMPATIBLE_PREVIOUS
Raw schemas
Raw input schema
Raw input schema
{
"additionalProperties": false,
"allOf": [
{
"else": {
"required": [
"mode",
"target"
]
},
"if": {
"properties": {
"mode": {
"const": "empty"
}
}
},
"then": {
"required": [
"mode",
"at"
]
}
},
{
"if": {
"properties": {
"sequence": {
"properties": {
"mode": {
"const": "continuePrevious"
}
},
"required": [
"mode"
]
}
},
"required": [
"sequence"
]
},
"then": {
"not": {
"anyOf": [
{
"required": [
"preset"
]
},
{
"required": [
"style"
]
}
]
}
}
}
],
"properties": {
"at": {
"$ref": "#/$defs/BlockAddress",
"description": "Required when mode is 'empty'. The paragraph to create the list at. Format: {kind:'block', nodeType:'paragraph', nodeId:'<id>'}."
},
"kind": {
"description": "List type: 'bullet' for bullet points, 'ordered' for numbered lists.",
"enum": [
"ordered",
"bullet"
]
},
"level": {
"description": "List nesting level (0-8). 0 is the top level.",
"maximum": 8,
"minimum": 0,
"type": "integer"
},
"mode": {
"description": "Required. 'fromParagraphs' converts existing paragraphs into list items: each paragraph becomes one item, so create one paragraph per item first. 'empty' creates a new empty list at 'at'.",
"enum": [
"empty",
"fromParagraphs"
]
},
"preset": {
"description": "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format.",
"enum": [
"decimal",
"decimalParenthesis",
"lowerLetter",
"upperLetter",
"lowerRoman",
"upperRoman",
"disc",
"circle",
"square",
"dash"
]
},
"sequence": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"mode": {
"const": "new"
},
"startAt": {
"minimum": 1,
"type": "integer"
}
},
"required": [
"mode"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"mode": {
"const": "continuePrevious"
}
},
"required": [
"mode"
],
"type": "object"
}
]
},
"style": {
"additionalProperties": false,
"properties": {
"levels": {
"items": {
"additionalProperties": false,
"properties": {
"alignment": {
"enum": [
"left",
"center",
"right"
]
},
"indents": {
"additionalProperties": false,
"properties": {
"firstLine": {
"type": "integer"
},
"hanging": {
"type": "integer"
},
"left": {
"type": "integer"
}
},
"type": "object"
},
"level": {
"maximum": 8,
"minimum": 0,
"type": "integer"
},
"lvlText": {
"type": "string"
},
"markerFont": {
"type": "string"
},
"numFmt": {
"type": "string"
},
"pictureBulletId": {
"type": "integer"
},
"start": {
"type": "integer"
},
"tabStopAt": {
"type": [
"integer",
"null"
]
},
"trailingCharacter": {
"enum": [
"tab",
"space",
"nothing"
]
}
},
"required": [
"level"
],
"type": "object"
},
"type": "array"
},
"version": {
"const": 1
}
},
"required": [
"version",
"levels"
],
"type": "object"
},
"target": {
"$ref": "#/$defs/BlockAddressOrRange",
"description": "Required when mode is 'fromParagraphs'. Each call converts ONE paragraph into a list item. To make a list with N items, create N separate paragraphs first, then call superdoc_list create for EACH one. Format: {kind:'block', nodeType:'paragraph', nodeId:'<id>'}."
}
},
"required": [
"mode"
],
"type": "object"
}
Raw output schema
Raw output schema
{
"oneOf": [
{
"additionalProperties": false,
"properties": {
"item": {
"$ref": "#/$defs/ListItemAddress"
},
"listId": {
"type": "string"
},
"success": {
"const": true
}
},
"required": [
"success",
"listId",
"item"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"failure": {
"additionalProperties": false,
"properties": {
"code": {
"enum": [
"INVALID_TARGET",
"LEVEL_OUT_OF_RANGE",
"INVALID_INPUT",
"NO_COMPATIBLE_PREVIOUS"
]
},
"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": {
"item": {
"$ref": "#/$defs/ListItemAddress"
},
"listId": {
"type": "string"
},
"success": {
"const": true
}
},
"required": [
"success",
"listId",
"item"
],
"type": "object"
}
Raw failure schema
Raw failure schema
{
"additionalProperties": false,
"properties": {
"failure": {
"additionalProperties": false,
"properties": {
"code": {
"enum": [
"INVALID_TARGET",
"LEVEL_OUT_OF_RANGE",
"INVALID_INPUT",
"NO_COMPATIBLE_PREVIOUS"
]
},
"details": {},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"success": {
"const": false
}
},
"required": [
"success",
"failure"
],
"type": "object"
}