create.sectionBreak

Create a section break at the target location with optional initial section properties.

Alpha: Document API is currently alpha and subject to breaking changes.

Summary

Create a section break at the target location with optional initial section properties.

• Operation ID: create.sectionBreak
• API member path: editor.doc.create.sectionBreak(...)
• Mutates document: yes
• Idempotency: non-idempotent
• Supports tracked mode: no
• Supports dry run: yes
• Deterministic target resolution: yes

Expected result

Returns a CreateSectionBreakResult with the new section break position and section address.

Input fields

Field	Type	Required	Description
at	object(kind=“documentStart”) \	object(kind=“documentEnd”) \	object(kind=“before”) \	object(kind=“after”)	no	One of: object(kind=“documentStart”), object(kind=“documentEnd”), object(kind=“before”), object(kind=“after”)
breakType	enum	no	"continuous", "nextPage", "evenPage", "oddPage"
headerFooterMargins	object	no
headerFooterMargins.footer	number	no
headerFooterMargins.header	number	no
pageMargins	object	no
pageMargins.bottom	number	no
pageMargins.gutter	number	no
pageMargins.left	number	no
pageMargins.right	number	no
pageMargins.top	number	no

Example request

{
  "at": {
    "kind": "documentStart"
  },
  "breakType": "continuous"
}

Output fields

Variant 1 (section.kind=“section”)

Field	Type	Required	Description
breakParagraph	BlockNodeAddress	no	BlockNodeAddress
breakParagraph.kind	"block"	no	Constant: "block"
breakParagraph.nodeId	string	no
breakParagraph.nodeType	enum	no	"paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt"
section	SectionAddress	yes	SectionAddress
section.kind	"section"	yes	Constant: "section"
section.sectionId	string	yes
success	true	yes	Constant: true

Variant 2 (success=false)

Field	Type	Required	Description
failure	object	yes
failure.code	enum	yes	"INVALID_TARGET", "CAPABILITY_UNAVAILABLE"
failure.details	any	no
failure.message	string	yes
success	false	yes	Constant: false

Example response

{
  "breakParagraph": {
    "kind": "block",
    "nodeId": "node-def456",
    "nodeType": "paragraph"
  },
  "section": {
    "kind": "section",
    "sectionId": "example"
  },
  "success": true
}

Pre-apply throws

• TARGET_NOT_FOUND
• INVALID_TARGET
• AMBIGUOUS_TARGET
• INVALID_INPUT
• CAPABILITY_UNAVAILABLE
• INTERNAL_ERROR

Non-applied failure codes

• INVALID_TARGET
• CAPABILITY_UNAVAILABLE

Raw schemas

Raw input schema

{
  "additionalProperties": false,
  "properties": {
    "at": {
      "oneOf": [
        {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "documentStart"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "documentEnd"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "before"
            },
            "target": {
              "$ref": "#/$defs/BlockNodeAddress"
            }
          },
          "required": [
            "kind",
            "target"
          ],
          "type": "object"
        },
        {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "after"
            },
            "target": {
              "$ref": "#/$defs/BlockNodeAddress"
            }
          },
          "required": [
            "kind",
            "target"
          ],
          "type": "object"
        }
      ]
    },
    "breakType": {
      "enum": [
        "continuous",
        "nextPage",
        "evenPage",
        "oddPage"
      ]
    },
    "headerFooterMargins": {
      "additionalProperties": false,
      "properties": {
        "footer": {
          "minimum": 0,
          "type": "number"
        },
        "header": {
          "minimum": 0,
          "type": "number"
        }
      },
      "type": "object"
    },
    "pageMargins": {
      "additionalProperties": false,
      "properties": {
        "bottom": {
          "minimum": 0,
          "type": "number"
        },
        "gutter": {
          "minimum": 0,
          "type": "number"
        },
        "left": {
          "minimum": 0,
          "type": "number"
        },
        "right": {
          "minimum": 0,
          "type": "number"
        },
        "top": {
          "minimum": 0,
          "type": "number"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Raw output schema

{
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "breakParagraph": {
          "$ref": "#/$defs/BlockNodeAddress"
        },
        "section": {
          "$ref": "#/$defs/SectionAddress"
        },
        "success": {
          "const": true
        }
      },
      "required": [
        "success",
        "section"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "failure": {
          "additionalProperties": false,
          "properties": {
            "code": {
              "enum": [
                "INVALID_TARGET",
                "CAPABILITY_UNAVAILABLE"
              ]
            },
            "details": {},
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object"
        },
        "success": {
          "const": false
        }
      },
      "required": [
        "success",
        "failure"
      ],
      "type": "object"
    }
  ]
}

Raw success schema

{
  "additionalProperties": false,
  "properties": {
    "breakParagraph": {
      "$ref": "#/$defs/BlockNodeAddress"
    },
    "section": {
      "$ref": "#/$defs/SectionAddress"
    },
    "success": {
      "const": true
    }
  },
  "required": [
    "success",
    "section"
  ],
  "type": "object"
}

Raw failure schema

{
  "additionalProperties": false,
  "properties": {
    "failure": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "enum": [
            "INVALID_TARGET",
            "CAPABILITY_UNAVAILABLE"
          ]
        },
        "details": {},
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "success": {
      "const": false
    }
  },
  "required": [
    "success",
    "failure"
  ],
  "type": "object"
}