Skip to main content
Document API gives you a consistent way to read and edit documents without relying on editor internals.
Document API is in alpha and subject to breaking changes while the contract and adapters continue to evolve. The current API is not yet comprehensive, and more commands and namespaces are being added on an ongoing basis.

​
Why use Document API

  • Build automations without editor-specific code.
  • Work with predictable inputs and outputs defined per operation.
  • Check capabilities up front and branch safely when features are unavailable.

​
Node addressing

Every block in a document has a nodeId — a string that uniquely identifies it. For mutation targeting and getNode(...), use NodeAddress: 
{
  "kind": "block",
  "nodeType": "paragraph",
  "nodeId": "3A2B1C0D"
}
find(...) returns NodeAddress values (for example kind: "block"). For text selectors, query.match(...) returns deterministic mutation-ready data: item.target as a canonical SelectionTarget, item.handle.ref as a reusable resolved handle, and item.address as the matching NodeAddress.

​
Mutation targeting

Core selection mutations such as replace, delete, format.*, and selection-based mutation plans use SelectionTarget or a mutation-ready ref. 
{
  "kind": "selection",
  "start": { "kind": "text", "blockId": "p1", "offset": 0 },
  "end": { "kind": "text", "blockId": "p1", "offset": 5 }
}
Use item.target from query.match(...) for single direct operations: 
const match = editor.doc.query.match({
  select: { type: 'text', pattern: 'ACME Corp' },
  require: 'first',
});

const target = match.items?.[0]?.target;
if (target) {
  editor.doc.replace({ target, text: 'NewCo Inc.' });
}
Use item.handle.ref when you want multiple operations or a mutation plan to reuse the same resolved range. When you need to construct a selection from explicit anchors, call editor.doc.ranges.resolve(...) and use its target or handle.ref.
SelectionTarget is the canonical target for core selection mutations. Other APIs, such as comments or insertion-point operations, may still use TextAddress where the operation is defined around a specific text span or insertion point.

​
Stable IDs across loads

For DOCX documents, nodeId is derived from the file’s native w14:paraId attribute. In practice, this is usually stable when you reopen the same unchanged DOCX across separate editor sessions, machines, or headless CLI pipelines. For nodes created at runtime (not imported from DOCX), nodeId falls back to sdBlockId, a UUID generated when the editor opens. This fallback is volatile and changes on every load.
ID sourceStable across loads?When used
paraId (from DOCX)Best effort (usually stable for unchanged DOCX blocks)Paragraphs and table rows imported from DOCX
sdBlockId (runtime)No (session-scoped)Nodes created programmatically before first export
If you need to reference blocks across separate editor sessions, use editor.doc.query.match() (or persist nodeId and reconstruct a NodeAddress) — don’t read node.attrs.sdBlockId directly. The Document API resolves paraId first for DOCX-imported content.
No block ID is guaranteed to survive all Microsoft Word round-trips or external document rewrites. Word and other tools may regenerate w14:paraId during structural changes (for example split/merge/rebuild operations), and SuperDoc may rewrite duplicate IDs on import to keep block targeting deterministic.