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 | |
at | SelectionTarget | no | SelectionTarget |
at.end | SelectionPoint | no | SelectionPoint |
at.kind | "selection" | no | Constant: "selection" |
at.start | SelectionPoint | no | SelectionPoint |
at.story | StoryLocator | no | StoryLocator |
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_FOUNDINVALID_TARGETAMBIGUOUS_TARGETINVALID_INPUTLOCK_VIOLATIONREVISION_MISMATCHCAPABILITY_UNAVAILABLE
Non-applied failure codes
INVALID_TARGETNO_OP
Raw schemas
Raw input schema
Raw input schema
{
"additionalProperties": false,
"properties": {
"alias": {
"type": "string"
},
"at": {
"$ref": "#/$defs/SelectionTarget"
},
"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
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
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
Raw failure schema
{
"additionalProperties": false,
"properties": {
"failure": {
"$ref": "#/$defs/ReceiptFailure"
},
"success": {
"const": false
}
},
"required": [
"success",
"failure"
],
"type": "object"
}