create.mdx

title	lists.create
sidebarTitle	lists.create
description	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.

{/* GENERATED FILE: DO NOT EDIT. Regenerate via pnpm run docapi:sync. */}

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"
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"
  },
  "listId": "example",
  "success": true
}

Pre-apply throws

• TARGET_NOT_FOUND
• CAPABILITY_UNAVAILABLE
• INVALID_TARGET
• INVALID_INPUT

Non-applied failure codes

• INVALID_TARGET
• LEVEL_OUT_OF_RANGE
• INVALID_INPUT
• NO_COMPATIBLE_PREVIOUS

Raw schemas

```json { "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:''}." }, "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:''}." } }, "required": [ "mode" ], "type": "object" } ``` ```json { "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" } ] } ``` ```json { "additionalProperties": false, "properties": { "item": { "$ref": "#/$defs/ListItemAddress" }, "listId": { "type": "string" }, "success": { "const": true } }, "required": [ "success", "listId", "item" ], "type": "object" } ``` ```json { "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" } ```