> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-nick-sd-2070-add-content-controls-namespace-to-doc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Document API

> A stable, engine-agnostic interface for programmatic document access

Document API gives you a consistent way to read and edit documents without relying on editor internals.

<Info>
  Document API is in <strong>alpha</strong> 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.
</Info>

## 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`:

```json theme={null}
{
  "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 source             | Stable 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 |

<Tip>
  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.
</Tip>

<Warning>
  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.
</Warning>