> ## Documentation Index
> Fetch the complete documentation index at: https://developers.myhero.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Docx search

> Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Refs expire after any mutation that changes the…

`docx_search`

Find text patterns or nodes in the document and get ref handles for targeting edits and formatting. Refs expire after any mutation that changes the document. Re-search before the next edit when using individual tools (docx\_edit, docx\_format). Within a docx\_mutations batch, selectors in "where" clauses resolve automatically at compile time; no manual re-searching needed between steps. Text search returns handle.ref covering only the matched substring. Node search finds blocks by type (paragraph, heading, table, listItem, etc.). The "require" parameter controls match cardinality: "first" returns one match, "all" returns every match, "exactlyOne" fails if not exactly one match. Supports scoping via "within" to search inside a single block. Do NOT use regex or markdown formatting markers (#, \*\*, etc.) in search patterns; patterns are plain text only. Do NOT use this tool when you already have a ref from docx\_get\_content blocks or docx\_create; use that ref directly.

## Parameters

**select** *required*

Search selector. Use \{type:'text', pattern:'...'} for text search or \{type:'node', nodeType:'paragraph'|'heading'|...} for node search.

**within** `object`

Limit search scope to within a specific block: \{kind:'block', nodeType:'...', nodeId:'...'}.

**require** `string, enum: 'any' | 'first' | 'exactlyOne' | 'all'`

Match cardinality: 'any' (all matches), 'first' (only first), 'exactlyOne' (fail if != 1), 'all' (fail if 0).

**mode** `string, enum: 'strict' | 'candidates'`

Search mode: 'strict' (default, exact matching) or 'candidates' (returns scored potential matches).

**includeNodes** `boolean`

When true, includes full node data in results. Default: false.

**limit** `number`

Maximum number of matches to return.

**offset** `number`

Number of matches to skip for pagination.

**documentId** `string` *required*

The HERO documentId of the docx to target.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.