Summary
Insert new linked text at a target position.- Operation ID:
hyperlinks.insert - API member path:
editor.doc.hyperlinks.insert(...) - Mutates document:
yes - Idempotency:
non-idempotent - Supports tracked mode:
no - Supports dry run:
yes - Deterministic target resolution:
yes
Expected result
Returns a HyperlinkMutationResult with the created hyperlink address on success, or a failure code.Input fields
| Field | Type | Required | Description |
|---|---|---|---|
link | object | yes | |
link.destination | object | yes | |
link.destination.anchor | string | no | |
link.destination.docLocation | string | no | |
link.destination.href | string | no | |
link.rel | string | no | |
link.target | string | no | |
link.tooltip | string | no | |
target | TextAddress | no | TextAddress |
target.blockId | string | no | |
target.kind | "text" | no | Constant: "text" |
target.range | Range | no | Range |
target.range.end | integer | no | |
target.range.start | integer | no | |
target.story | StoryLocator | no | StoryLocator |
text | string | yes |
Example request
{
"link": {
"destination": {
"anchor": "example",
"href": "example"
},
"target": "example",
"tooltip": "example"
},
"target": {
"blockId": "block-abc123",
"kind": "text",
"range": {
"end": 10,
"start": 0
},
"story": {
"kind": "story",
"storyType": "body"
}
},
"text": "Hello, world."
}
Output fields
Variant 1 (success=true)
| Field | Type | Required | Description |
|---|---|---|---|
hyperlink | object(kind=“inline”) | yes | |
hyperlink.anchor | InlineAnchor | yes | InlineAnchor |
hyperlink.anchor.end | Position | yes | Position |
hyperlink.anchor.end.blockId | string | yes | |
hyperlink.anchor.end.offset | integer | yes | |
hyperlink.anchor.start | Position | yes | Position |
hyperlink.anchor.start.blockId | string | yes | |
hyperlink.anchor.start.offset | integer | yes | |
hyperlink.kind | "inline" | yes | Constant: "inline" |
hyperlink.nodeType | "hyperlink" | yes | Constant: "hyperlink" |
success | true | yes | Constant: true |
Variant 2 (success=false)
| Field | Type | Required | Description |
|---|---|---|---|
failure | object | yes | |
failure.code | enum | yes | "NO_OP", "INVALID_TARGET", "TARGET_NOT_FOUND", "CAPABILITY_UNAVAILABLE" |
failure.details | object | no | |
failure.message | string | yes | |
success | false | yes | Constant: false |
Example response
{
"hyperlink": {
"anchor": {
"end": {
"blockId": "block-abc123",
"offset": 0
},
"start": {
"blockId": "block-abc123",
"offset": 0
}
},
"kind": "inline",
"nodeType": "hyperlink"
},
"success": true
}
Pre-apply throws
TARGET_NOT_FOUNDCAPABILITY_UNAVAILABLEINVALID_TARGETINVALID_INPUT
Non-applied failure codes
NO_OPINVALID_TARGET
Raw schemas
Raw input schema
Raw input schema
{
"additionalProperties": false,
"properties": {
"link": {
"additionalProperties": false,
"properties": {
"destination": {
"additionalProperties": false,
"properties": {
"anchor": {
"type": "string"
},
"docLocation": {
"type": "string"
},
"href": {
"type": "string"
}
},
"type": "object"
},
"rel": {
"type": "string"
},
"target": {
"type": "string"
},
"tooltip": {
"type": "string"
}
},
"required": [
"destination"
],
"type": "object"
},
"target": {
"$ref": "#/$defs/TextAddress"
},
"text": {
"type": "string"
}
},
"required": [
"text",
"link"
],
"type": "object"
}
Raw output schema
Raw output schema
{
"oneOf": [
{
"additionalProperties": false,
"properties": {
"hyperlink": {
"additionalProperties": false,
"properties": {
"anchor": {
"$ref": "#/$defs/InlineAnchor"
},
"kind": {
"const": "inline"
},
"nodeType": {
"const": "hyperlink"
}
},
"required": [
"kind",
"nodeType",
"anchor"
],
"type": "object"
},
"success": {
"const": true
}
},
"required": [
"success",
"hyperlink"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"failure": {
"additionalProperties": false,
"properties": {
"code": {
"enum": [
"NO_OP",
"INVALID_TARGET",
"TARGET_NOT_FOUND",
"CAPABILITY_UNAVAILABLE"
]
},
"details": {
"type": "object"
},
"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": {
"hyperlink": {
"additionalProperties": false,
"properties": {
"anchor": {
"$ref": "#/$defs/InlineAnchor"
},
"kind": {
"const": "inline"
},
"nodeType": {
"const": "hyperlink"
}
},
"required": [
"kind",
"nodeType",
"anchor"
],
"type": "object"
},
"success": {
"const": true
}
},
"required": [
"success",
"hyperlink"
],
"type": "object"
}
Raw failure schema
Raw failure schema
{
"additionalProperties": false,
"properties": {
"failure": {
"additionalProperties": false,
"properties": {
"code": {
"enum": [
"NO_OP",
"INVALID_TARGET",
"TARGET_NOT_FOUND",
"CAPABILITY_UNAVAILABLE"
]
},
"details": {
"type": "object"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"success": {
"const": false
}
},
"required": [
"success",
"failure"
],
"type": "object"
}