Summary
Insert a new cross-reference field at a target location.- Operation ID:
crossRefs.insert - API member path:
editor.doc.crossRefs.insert(...) - Mutates document:
yes - Idempotency:
non-idempotent - Supports tracked mode:
no - Supports dry run:
yes - Deterministic target resolution:
yes
Expected result
Returns a CrossRefMutationResult indicating success with the cross-reference address or a failure.Input fields
| Field | Type | Required | Description |
|---|---|---|---|
at | TextTarget | yes | TextTarget |
at.kind | "text" | yes | Constant: "text" |
at.segments | TextSegment[] | yes | |
at.story | StoryLocator | no | StoryLocator |
display | enum | yes | "content", "pageNumber", "noteNumber", "labelAndNumber", "aboveBelow", "numberOnly", "numberFullContext", "styledContent", "styledPageNumber" |
target | object(kind=“bookmark”) | object(kind=“heading”) | object(kind=“note”) | object(kind=“caption”) | object(kind=“numberedItem”) | object(kind=“styledParagraph”) | yes | One of: object(kind=“bookmark”), object(kind=“heading”), object(kind=“note”), object(kind=“caption”), object(kind=“numberedItem”), object(kind=“styledParagraph”) |
Example request
{
"at": {
"kind": "text",
"segments": [
{
"blockId": "block-abc123",
"range": {
"end": 10,
"start": 0
}
}
],
"story": {
"kind": "story",
"storyType": "body"
}
},
"display": "content",
"target": {
"kind": "bookmark",
"name": "example"
}
}
Output fields
Variant 1 (success=true)
| Field | Type | Required | Description |
|---|---|---|---|
crossRef | object(kind=“inline”) | yes | |
crossRef.anchor | InlineAnchor | yes | InlineAnchor |
crossRef.anchor.end | Position | yes | Position |
crossRef.anchor.end.blockId | string | yes | |
crossRef.anchor.end.offset | integer | yes | |
crossRef.anchor.start | Position | yes | Position |
crossRef.anchor.start.blockId | string | yes | |
crossRef.anchor.start.offset | integer | yes | |
crossRef.kind | "inline" | yes | Constant: "inline" |
crossRef.nodeType | "crossRef" | yes | Constant: "crossRef" |
success | true | yes | Constant: true |
Variant 2 (success=false)
| Field | Type | Required | Description |
|---|---|---|---|
failure | object | yes | |
failure.code | string | yes | |
failure.details | any | no | |
failure.message | string | yes | |
success | false | yes | Constant: false |
Example response
{
"crossRef": {
"anchor": {
"end": {
"blockId": "block-abc123",
"offset": 0
},
"start": {
"blockId": "block-abc123",
"offset": 0
}
},
"kind": "inline",
"nodeType": "crossRef"
},
"success": true
}
Pre-apply throws
TARGET_NOT_FOUNDINVALID_TARGETINVALID_INPUTCAPABILITY_UNAVAILABLE
Non-applied failure codes
- None
Raw schemas
Raw input schema
Raw input schema
{
"additionalProperties": false,
"properties": {
"at": {
"$ref": "#/$defs/TextTarget"
},
"display": {
"enum": [
"content",
"pageNumber",
"noteNumber",
"labelAndNumber",
"aboveBelow",
"numberOnly",
"numberFullContext",
"styledContent",
"styledPageNumber"
]
},
"target": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "bookmark"
},
"name": {
"type": "string"
}
},
"required": [
"kind",
"name"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "heading"
},
"nodeId": {
"type": "string"
}
},
"required": [
"kind",
"nodeId"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "note"
},
"noteId": {
"type": "string"
}
},
"required": [
"kind",
"noteId"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "caption"
},
"nodeId": {
"type": "string"
}
},
"required": [
"kind",
"nodeId"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"const": "numberedItem"
},
"nodeId": {
"type": "string"
}
},
"required": [
"kind",
"nodeId"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"direction": {
"enum": [
"before",
"after"
]
},
"kind": {
"const": "styledParagraph"
},
"styleName": {
"type": "string"
}
},
"required": [
"kind",
"styleName"
],
"type": "object"
}
]
}
},
"required": [
"at",
"target",
"display"
],
"type": "object"
}
Raw output schema
Raw output schema
{
"oneOf": [
{
"additionalProperties": false,
"properties": {
"crossRef": {
"additionalProperties": false,
"properties": {
"anchor": {
"$ref": "#/$defs/InlineAnchor"
},
"kind": {
"const": "inline"
},
"nodeType": {
"const": "crossRef"
}
},
"required": [
"kind",
"nodeType",
"anchor"
],
"type": "object"
},
"success": {
"const": true
}
},
"required": [
"success",
"crossRef"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"failure": {
"additionalProperties": false,
"properties": {
"code": {
"type": "string"
},
"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": {
"crossRef": {
"additionalProperties": false,
"properties": {
"anchor": {
"$ref": "#/$defs/InlineAnchor"
},
"kind": {
"const": "inline"
},
"nodeType": {
"const": "crossRef"
}
},
"required": [
"kind",
"nodeType",
"anchor"
],
"type": "object"
},
"success": {
"const": true
}
},
"required": [
"success",
"crossRef"
],
"type": "object"
}
Raw failure schema
Raw failure schema
{
"additionalProperties": false,
"properties": {
"failure": {
"additionalProperties": false,
"properties": {
"code": {
"type": "string"
},
"details": {},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"success": {
"const": false
}
},
"required": [
"success",
"failure"
],
"type": "object"
}