create.contentControl

Create a new content control (SDT) in the document.

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

Summary

Create a new content control (SDT) in the document.

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

Expected result

Returns a ContentControlMutationResult with the created content control target.

Input fields

Field	Type	Required	Description
alias	string	no
content	string	no
controlType	string	no
kind	enum	yes	"block", "inline"
lockMode	enum	no	"unlocked", "sdtLocked", "contentLocked", "sdtContentLocked"
tag	string	no
target	object(nodeType=“sdt”)	no
target.kind	enum	no	"block", "inline"
target.nodeId	string	no
target.nodeType	"sdt"	no	Constant: "sdt"

Example request

{
  "controlType": "example",
  "kind": "block",
  "target": {
    "kind": "block",
    "nodeId": "node-def456",
    "nodeType": "sdt"
  }
}

Output fields

Variant 1 (success=true)

Field	Type	Required	Description
contentControl	object(nodeType=“sdt”)	yes
contentControl.kind	enum	yes	"block", "inline"
contentControl.nodeId	string	yes
contentControl.nodeType	"sdt"	yes	Constant: "sdt"
success	true	yes	Constant: true
updatedRef	object(nodeType=“sdt”)	no
updatedRef.kind	enum	no	"block", "inline"
updatedRef.nodeId	string	no
updatedRef.nodeType	"sdt"	no	Constant: "sdt"

Variant 2 (success=false)

Field	Type	Required	Description
failure	ReceiptFailure	yes	ReceiptFailure
failure.code	string	yes
failure.details	any	no
failure.message	string	yes
success	false	yes	Constant: false

Example response

{
  "contentControl": {
    "kind": "block",
    "nodeId": "node-def456",
    "nodeType": "sdt"
  },
  "success": true,
  "updatedRef": {
    "kind": "block",
    "nodeId": "node-def456",
    "nodeType": "sdt"
  }
}

Pre-apply throws

• TARGET_NOT_FOUND
• INVALID_TARGET
• AMBIGUOUS_TARGET
• INVALID_INPUT
• LOCK_VIOLATION
• REVISION_MISMATCH
• CAPABILITY_UNAVAILABLE

Non-applied failure codes

• INVALID_TARGET
• NO_OP

Raw schemas

Raw input schema

{
  "additionalProperties": false,
  "properties": {
    "alias": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "controlType": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "block",
        "inline"
      ]
    },
    "lockMode": {
      "enum": [
        "unlocked",
        "sdtLocked",
        "contentLocked",
        "sdtContentLocked"
      ]
    },
    "tag": {
      "type": "string"
    },
    "target": {
      "additionalProperties": false,
      "properties": {
        "kind": {
          "enum": [
            "block",
            "inline"
          ]
        },
        "nodeId": {
          "type": "string"
        },
        "nodeType": {
          "const": "sdt"
        }
      },
      "required": [
        "kind",
        "nodeType",
        "nodeId"
      ],
      "type": "object"
    }
  },
  "required": [
    "kind"
  ],
  "type": "object"
}

Raw output schema

{
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "contentControl": {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "enum": [
                "block",
                "inline"
              ]
            },
            "nodeId": {
              "type": "string"
            },
            "nodeType": {
              "const": "sdt"
            }
          },
          "required": [
            "kind",
            "nodeType",
            "nodeId"
          ],
          "type": "object"
        },
        "success": {
          "const": true
        },
        "updatedRef": {
          "additionalProperties": false,
          "properties": {
            "kind": {
              "enum": [
                "block",
                "inline"
              ]
            },
            "nodeId": {
              "type": "string"
            },
            "nodeType": {
              "const": "sdt"
            }
          },
          "required": [
            "kind",
            "nodeType",
            "nodeId"
          ],
          "type": "object"
        }
      },
      "required": [
        "success",
        "contentControl"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "failure": {
          "$ref": "#/$defs/ReceiptFailure"
        },
        "success": {
          "const": false
        }
      },
      "required": [
        "success",
        "failure"
      ],
      "type": "object"
    }
  ]
}

Raw success schema

{
  "additionalProperties": false,
  "properties": {
    "contentControl": {
      "additionalProperties": false,
      "properties": {
        "kind": {
          "enum": [
            "block",
            "inline"
          ]
        },
        "nodeId": {
          "type": "string"
        },
        "nodeType": {
          "const": "sdt"
        }
      },
      "required": [
        "kind",
        "nodeType",
        "nodeId"
      ],
      "type": "object"
    },
    "success": {
      "const": true
    },
    "updatedRef": {
      "additionalProperties": false,
      "properties": {
        "kind": {
          "enum": [
            "block",
            "inline"
          ]
        },
        "nodeId": {
          "type": "string"
        },
        "nodeType": {
          "const": "sdt"
        }
      },
      "required": [
        "kind",
        "nodeType",
        "nodeId"
      ],
      "type": "object"
    }
  },
  "required": [
    "success",
    "contentControl"
  ],
  "type": "object"
}

Raw failure schema

{
  "additionalProperties": false,
  "properties": {
    "failure": {
      "$ref": "#/$defs/ReceiptFailure"
    },
    "success": {
      "const": false
    }
  },
  "required": [
    "success",
    "failure"
  ],
  "type": "object"
}