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 SDM/1 SDAddress values (for example kind: "content"), while query.match(...) returns NodeAddress values (kind: "block" / kind: "inline"). Use query.match(...) when you need deterministic mutation-ready refs and node addresses.

​
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, tables, rows, cells 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.