Alpha: Document API is currently alpha and subject to breaking changes.
Summary
Search the document for nodes matching type, text, or attribute criteria.- Operation ID:
find - API member path:
editor.doc.find(...) - Mutates document:
no - Idempotency:
idempotent - Supports tracked mode:
no - Supports dry run:
no - Deterministic target resolution:
no
Expected result
Returns a FindOutput with matched items array and total count, or an empty items array if no nodes match.Input fields
| Field | Type | Required | Description | ||
|---|---|---|---|---|---|
includeNodes | boolean | no | |||
includeUnknown | boolean | no | |||
limit | integer | no | |||
offset | integer | no | |||
require | enum | no | "any", "first", "exactlyOne", "all" | ||
select | object(type=“text”) \ | object(type=“node”) \ | object | yes | One of: object(type=“text”), object(type=“node”), object |
within | NodeAddress | no | NodeAddress |
Example request
{
"limit": 50,
"select": {
"caseSensitive": true,
"mode": "contains",
"pattern": "hello world",
"type": "text"
},
"within": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "paragraph"
}
}
Output fields
| Field | Type | Required | Description |
|---|---|---|---|
diagnostics | object[] | no | |
evaluatedRevision | string | yes | |
items | object[] | yes | |
page | PageInfo | yes | PageInfo |
page.limit | integer | yes | |
page.offset | integer | yes | |
page.returned | integer | yes | |
total | integer | yes |
Example response
{
"diagnostics": [
{
"address": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "paragraph"
},
"hint": "example",
"message": "Operation failed."
}
],
"evaluatedRevision": "rev-001",
"items": [
{
"address": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "paragraph"
},
"context": {
"address": {
"kind": "block",
"nodeId": "node-def456",
"nodeType": "paragraph"
},
"highlightRange": {
"end": 10,
"start": 0
},
"snippet": "...the quick brown fox...",
"textRanges": [
{
"blockId": "block-abc123",
"kind": "text",
"range": {
"end": 10,
"start": 0
}
}
]
},
"handle": {
"ref": "handle:abc123",
"refStability": "stable",
"targetKind": "text"
},
"id": "id-001",
"node": {
"kind": "block",
"nodeType": "paragraph",
"summary": {
"label": "Paragraph 1",
"text": "Hello, world."
},
"text": "Hello, world."
}
}
],
"page": {
"limit": 50,
"offset": 0,
"returned": 1
},
"total": 1
}
Pre-apply throws
CAPABILITY_UNAVAILABLEINVALID_INPUT
Non-applied failure codes
- None
Raw schemas
Raw input schema
Raw input schema
{
"additionalProperties": false,
"properties": {
"includeNodes": {
"type": "boolean"
},
"includeUnknown": {
"type": "boolean"
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"require": {
"enum": [
"any",
"first",
"exactlyOne",
"all"
]
},
"select": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"caseSensitive": {
"type": "boolean"
},
"mode": {
"enum": [
"contains",
"regex"
]
},
"pattern": {
"type": "string"
},
"type": {
"const": "text"
}
},
"required": [
"type",
"pattern"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"block",
"inline"
]
},
"nodeType": {
"enum": [
"paragraph",
"heading",
"listItem",
"table",
"tableRow",
"tableCell",
"tableOfContents",
"image",
"sdt",
"run",
"bookmark",
"comment",
"hyperlink",
"footnoteRef",
"tab",
"lineBreak"
]
},
"type": {
"const": "node"
}
},
"required": [
"type"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"nodeType": {
"enum": [
"paragraph",
"heading",
"listItem",
"table",
"tableRow",
"tableCell",
"tableOfContents",
"image",
"sdt",
"run",
"bookmark",
"comment",
"hyperlink",
"footnoteRef",
"tab",
"lineBreak"
]
}
},
"required": [
"nodeType"
],
"type": "object"
}
]
},
"within": {
"$ref": "#/$defs/NodeAddress"
}
},
"required": [
"select"
],
"type": "object"
}
Raw output schema
Raw output schema
{
"additionalProperties": false,
"properties": {
"diagnostics": {
"items": {
"additionalProperties": false,
"properties": {
"address": {
"$ref": "#/$defs/NodeAddress"
},
"hint": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"message"
],
"type": "object"
},
"type": "array"
},
"evaluatedRevision": {
"type": "string"
},
"items": {
"items": {
"additionalProperties": false,
"properties": {
"address": {
"$ref": "#/$defs/NodeAddress"
},
"context": {
"additionalProperties": false,
"properties": {
"address": {
"$ref": "#/$defs/NodeAddress"
},
"highlightRange": {
"$ref": "#/$defs/Range"
},
"snippet": {
"type": "string"
},
"textRanges": {
"items": {
"$ref": "#/$defs/TextAddress"
},
"type": "array"
}
},
"required": [
"address",
"snippet",
"highlightRange"
],
"type": "object"
},
"handle": {
"$ref": "#/$defs/ResolvedHandle"
},
"id": {
"type": "string"
},
"node": {
"additionalProperties": false,
"properties": {
"bodyNodes": {
"items": {
"type": "object"
},
"type": "array"
},
"bodyText": {
"type": "string"
},
"kind": {
"enum": [
"block",
"inline"
]
},
"nodes": {
"items": {
"type": "object"
},
"type": "array"
},
"nodeType": {
"enum": [
"paragraph",
"heading",
"listItem",
"table",
"tableRow",
"tableCell",
"tableOfContents",
"image",
"sdt",
"run",
"bookmark",
"comment",
"hyperlink",
"footnoteRef",
"tab",
"lineBreak"
]
},
"properties": {
"type": "object"
},
"summary": {
"additionalProperties": false,
"properties": {
"label": {
"type": "string"
},
"text": {
"type": "string"
}
},
"type": "object"
},
"text": {
"type": "string"
}
},
"required": [
"nodeType",
"kind"
],
"type": "object"
}
},
"required": [
"id",
"handle",
"address"
],
"type": "object"
},
"type": "array"
},
"page": {
"$ref": "#/$defs/PageInfo"
},
"total": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"evaluatedRevision",
"total",
"items",
"page"
],
"type": "object"
}