.docx files from Node.js or Python. They manage the CLI process for you and expose typed methods for every operation.
The SDKs are in alpha. The API surface matches the Document API and will evolve alongside it.
Installation
- Node.js
- Python
Quick start
The Node SDK supports both ESM and CommonJS:- Node.js (ESM)
- Node.js (CJS)
- Python
defaultChangeMode: 'tracked' (Node) or default_change_mode='tracked' (Python) to make mutations use tracked changes by default. If you pass changeMode on a specific call, that explicit value overrides the default.
The Python SDK also exposes synchronous SuperDocClient with the same doc.* operations when you prefer non-async code paths.
User identity
By default the SDK attributes edits to a generic “CLI” user. Setuser on the client to identify your automation in comments, tracked changes, and collaboration presence:
- Node.js
- Python
user is injected into every doc.open call. If you pass userName or userEmail on a specific doc.open, those per-call values take precedence.
Collaboration sessions
Use this when your app already has a live collaboration room (Liveblocks, Hocuspocus, or SuperDoc Yjs).Join an existing room
PasscollabUrl and collabDocumentId to doc.open:
- Node.js
- Python
Start an empty room from a local .docx
If the room is empty, pass doc together with collaboration params:
- Node.js
- Python
doc:
| Room state | Result |
|---|---|
| Room already has content | SDK joins the room. doc is ignored. |
Room is empty and doc is provided | SDK seeds the room from doc, then joins. |
Room is empty and no doc is provided | SDK starts a blank document. |
Control empty-room behavior
| Parameter | Type | Default | Description |
|---|---|---|---|
collabUrl | string | — | WebSocket URL for your collaboration provider. |
collabDocumentId | string | session ID | Room/document ID on the provider. |
doc | string | — | Local .docx used only when the room is empty. |
onMissing | string | seedFromDoc | seedFromDoc, blank, or error. |
bootstrapSettlingMs | number | 1500 | Wait time (ms) before seeding to avoid race conditions. |
onMissing: 'error'.
- Node.js
- Python
Check if the SDK seeded or joined
doc.open returns bootstrap details in collaboration mode:
- Node.js
- Python
Available operations
The SDKs expose all operations from the Document API plus lifecycle and session commands. The tables below are grouped by category.- Node.js
- Python
Lifecycle
| Operation | CLI command | Description |
|---|---|---|
doc.open | open | Open a document and create a persistent editing session. Optionally override the document body with contentOverride + overrideType (markdown, html, or text). |
doc.save | save | Save the current session to the original file or a new path. |
doc.close | close | Close the active editing session and clean up resources. |
Query
| Operation | CLI command | Description |
|---|---|---|
doc.find | find | Search the document for nodes matching type, text, or attribute criteria. |
doc.getNode | get-node | Retrieve a single node by target position. |
doc.getNodeById | get-node-by-id | Retrieve a single node by its unique ID. |
doc.getText | get-text | Extract the plain-text content of the document. |
doc.getMarkdown | get-markdown | Extract the document content as a Markdown string. |
doc.getHtml | get-html | Extract the document content as an HTML string. |
doc.info | info | Return document metadata including revision, node count, and capabilities. |
doc.query.match | query match | Deterministic selector-based search with cardinality contracts for mutation targeting. |
doc.mutations.preview | mutations preview | Dry-run a mutation plan, returning resolved targets without applying changes. |
Mutation
| Operation | CLI command | Description |
|---|---|---|
doc.insert | insert | Insert content at a target position, or at the end of the document when target is omitted. Supports text (default), markdown, and html content types via the type field. |
doc.replace | replace | Replace content at a target position with new text or inline content. |
doc.delete | delete | Delete content at a target position. |
doc.mutations.apply | mutations apply | Execute a mutation plan atomically against the document. |
Format
| Operation | CLI command | Description |
|---|---|---|
doc.format.apply | format apply | Apply inline run-property patch changes to the target range with explicit set/clear semantics. |
doc.format.bold | format bold | Set or clear the bold inline run property on the target text range. |
doc.format.italic | format italic | Set or clear the italic inline run property on the target text range. |
doc.format.strike | format strike | Set or clear the strike inline run property on the target text range. |
doc.format.underline | format underline | Set or clear the underline inline run property on the target text range. |
doc.format.highlight | format highlight | Set or clear the highlight inline run property on the target text range. |
doc.format.color | format color | Set or clear the color inline run property on the target text range. |
doc.format.fontSize | format font-size | Set or clear the fontSize inline run property on the target text range. |
doc.format.fontFamily | format font-family | Set or clear the fontFamily inline run property on the target text range. |
doc.format.letterSpacing | format letter-spacing | Set or clear the letterSpacing inline run property on the target text range. |
doc.format.vertAlign | format vert-align | Set or clear the vertAlign inline run property on the target text range. |
doc.format.position | format position | Set or clear the position inline run property on the target text range. |
doc.format.dstrike | format dstrike | Set or clear the dstrike inline run property on the target text range. |
doc.format.smallCaps | format small-caps | Set or clear the smallCaps inline run property on the target text range. |
doc.format.caps | format caps | Set or clear the caps inline run property on the target text range. |
doc.format.shading | format shading | Set or clear the shading inline run property on the target text range. |
doc.format.border | format border | Set or clear the border inline run property on the target text range. |
doc.format.outline | format outline | Set or clear the outline inline run property on the target text range. |
doc.format.shadow | format shadow | Set or clear the shadow inline run property on the target text range. |
doc.format.emboss | format emboss | Set or clear the emboss inline run property on the target text range. |
doc.format.imprint | format imprint | Set or clear the imprint inline run property on the target text range. |
doc.format.charScale | format char-scale | Set or clear the charScale inline run property on the target text range. |
doc.format.kerning | format kerning | Set or clear the kerning inline run property on the target text range. |
doc.format.vanish | format vanish | Set or clear the vanish inline run property on the target text range. |
doc.format.webHidden | format web-hidden | Set or clear the webHidden inline run property on the target text range. |
doc.format.specVanish | format spec-vanish | Set or clear the specVanish inline run property on the target text range. |
doc.format.rtl | format rtl | Set or clear the rtl inline run property on the target text range. |
doc.format.cs | format cs | Set or clear the cs inline run property on the target text range. |
doc.format.bCs | format b-cs | Set or clear the bCs inline run property on the target text range. |
doc.format.iCs | format i-cs | Set or clear the iCs inline run property on the target text range. |
doc.format.eastAsianLayout | format east-asian-layout | Set or clear the eastAsianLayout inline run property on the target text range. |
doc.format.em | format em | Set or clear the em inline run property on the target text range. |
doc.format.fitText | format fit-text | Set or clear the fitText inline run property on the target text range. |
doc.format.snapToGrid | format snap-to-grid | Set or clear the snapToGrid inline run property on the target text range. |
doc.format.lang | format lang | Set or clear the lang inline run property on the target text range. |
doc.format.oMath | format o-math | Set or clear the oMath inline run property on the target text range. |
doc.format.rStyle | format r-style | Set or clear the rStyle inline run property on the target text range. |
doc.format.rFonts | format r-fonts | Set or clear the rFonts inline run property on the target text range. |
doc.format.fontSizeCs | format font-size-cs | Set or clear the fontSizeCs inline run property on the target text range. |
doc.format.ligatures | format ligatures | Set or clear the ligatures inline run property on the target text range. |
doc.format.numForm | format num-form | Set or clear the numForm inline run property on the target text range. |
doc.format.numSpacing | format num-spacing | Set or clear the numSpacing inline run property on the target text range. |
doc.format.stylisticSets | format stylistic-sets | Set or clear the stylisticSets inline run property on the target text range. |
doc.format.contextualAlternates | format contextual-alternates | Set or clear the contextualAlternates inline run property on the target text range. |
Format / Paragraph
| Operation | CLI command | Description |
|---|---|---|
doc.format.paragraph.resetDirectFormatting | format paragraph reset-direct-formatting | Strip all direct paragraph formatting while preserving style reference, numbering, and section metadata. |
doc.format.paragraph.setAlignment | format paragraph set-alignment | Set paragraph alignment (justification) on a paragraph-like block. |
doc.format.paragraph.clearAlignment | format paragraph clear-alignment | Remove direct paragraph alignment, reverting to style-defined or default alignment. |
doc.format.paragraph.setIndentation | format paragraph set-indentation | Set paragraph indentation properties (left, right, firstLine, hanging) in twips. |
doc.format.paragraph.clearIndentation | format paragraph clear-indentation | Remove all direct paragraph indentation. |
doc.format.paragraph.setSpacing | format paragraph set-spacing | Set paragraph spacing properties (before, after, line, lineRule) in twips. |
doc.format.paragraph.clearSpacing | format paragraph clear-spacing | Remove all direct paragraph spacing. |
doc.format.paragraph.setKeepOptions | format paragraph set-keep-options | Set keep-with-next, keep-lines-together, and widow/orphan control flags. |
doc.format.paragraph.setOutlineLevel | format paragraph set-outline-level | Set the paragraph outline level (0–9) or null to clear. |
doc.format.paragraph.setFlowOptions | format paragraph set-flow-options | Set contextual spacing, page-break-before, and suppress-auto-hyphens flags. |
doc.format.paragraph.setTabStop | format paragraph set-tab-stop | Add or replace a tab stop at a given position. |
doc.format.paragraph.clearTabStop | format paragraph clear-tab-stop | Remove a tab stop at a given position. |
doc.format.paragraph.clearAllTabStops | format paragraph clear-all-tab-stops | Remove all tab stops from a paragraph. |
doc.format.paragraph.setBorder | format paragraph set-border | Set border properties for a specific side of a paragraph. |
doc.format.paragraph.clearBorder | format paragraph clear-border | Remove border for a specific side or all sides of a paragraph. |
doc.format.paragraph.setShading | format paragraph set-shading | Set paragraph shading (background fill, pattern color, pattern type). |
doc.format.paragraph.clearShading | format paragraph clear-shading | Remove all paragraph shading. |
Styles
| Operation | CLI command | Description |
|---|---|---|
doc.styles.apply | styles apply | Apply document-level default style changes to the stylesheet (word/styles.xml). Targets docDefaults run and paragraph channels with set-style patch semantics. |
Styles / Paragraph
| Operation | CLI command | Description |
|---|---|---|
doc.styles.paragraph.setStyle | styles paragraph set-style | Set the paragraph style reference (w:pStyle) on a paragraph-like block. |
doc.styles.paragraph.clearStyle | styles paragraph clear-style | Remove the paragraph style reference from a paragraph-like block. |
Create
| Operation | CLI command | Description |
|---|---|---|
doc.create.paragraph | create paragraph | Create a new paragraph at the target position. |
doc.create.heading | create heading | Create a new heading at the target position. |
doc.create.sectionBreak | create section-break | Create a section break at the target location with optional initial section properties. |
doc.create.table | create table | Create a new table at the target position. |
doc.create.tableOfContents | create table-of-contents | Insert a new table of contents at the target position. |
doc.create.image | create image | Insert a new image at the target position. |
Sections
| Operation | CLI command | Description |
|---|---|---|
doc.sections.list | sections list | List sections in deterministic order with section-target handles. |
doc.sections.get | sections get | Retrieve full section information by section address. |
doc.sections.setBreakType | sections set-break-type | Set the section break type. |
doc.sections.setPageMargins | sections set-page-margins | Set page-edge margins for a section. |
doc.sections.setHeaderFooterMargins | sections set-header-footer-margins | Set header/footer margin distances for a section. |
doc.sections.setPageSetup | sections set-page-setup | Set page size/orientation properties for a section. |
doc.sections.setColumns | sections set-columns | Set column configuration for a section. |
doc.sections.setLineNumbering | sections set-line-numbering | Enable or configure line numbering for a section. |
doc.sections.setPageNumbering | sections set-page-numbering | Set page numbering format/start for a section. |
doc.sections.setTitlePage | sections set-title-page | Enable or disable title-page behavior for a section. |
doc.sections.setOddEvenHeadersFooters | sections set-odd-even-headers-footers | Enable or disable odd/even header-footer mode in document settings. |
doc.sections.setVerticalAlign | sections set-vertical-align | Set vertical page alignment for a section. |
doc.sections.setSectionDirection | sections set-section-direction | Set section text flow direction (LTR/RTL). |
doc.sections.setHeaderFooterRef | sections set-header-footer-ref | Set or replace a section header/footer reference for a variant. |
doc.sections.clearHeaderFooterRef | sections clear-header-footer-ref | Clear a section header/footer reference for a specific variant. |
doc.sections.setLinkToPrevious | sections set-link-to-previous | Set or clear link-to-previous behavior for a header/footer variant. |
doc.sections.setPageBorders | sections set-page-borders | Set page border configuration for a section. |
doc.sections.clearPageBorders | sections clear-page-borders | Clear page border configuration for a section. |
Blocks
| Operation | CLI command | Description |
|---|---|---|
doc.blocks.delete | blocks delete | Delete an entire block node (paragraph, heading, list item, table, image, or sdt) deterministically. |
Lists
| Operation | CLI command | Description |
|---|---|---|
doc.lists.list | lists list | List all list nodes in the document, optionally filtered by scope. |
doc.lists.get | lists get | Retrieve a specific list node by target. |
doc.lists.insert | lists insert | Insert a new list at the target position. |
doc.lists.create | lists create | Create a new list from one or more paragraphs, or convert existing paragraphs into a new list. |
doc.lists.attach | lists attach | Convert non-list paragraphs to list items under an existing list sequence. |
doc.lists.detach | lists detach | Remove numbering properties from list items, converting them to plain paragraphs. |
doc.lists.indent | lists indent | Increase the indentation level of a list item. |
doc.lists.outdent | lists outdent | Decrease the indentation level of a list item. |
doc.lists.join | lists join | Merge two adjacent list sequences into one. |
doc.lists.canJoin | lists can-join | Check whether two adjacent list sequences can be joined. |
doc.lists.separate | lists separate | Split a list sequence at the target item, creating a new sequence from that point forward. |
doc.lists.setLevel | lists set-level | Set the absolute nesting level (0..8) of a list item. |
doc.lists.setValue | lists set-value | Set an explicit numbering value at the target item. Mid-sequence targets are atomically separated first. |
doc.lists.continuePrevious | lists continue-previous | Continue numbering from the nearest compatible previous list sequence. |
doc.lists.canContinuePrevious | lists can-continue-previous | Check whether the target sequence can continue numbering from a previous compatible sequence. |
doc.lists.setLevelRestart | lists set-level-restart | Set the restart behavior for a specific list level. |
doc.lists.convertToText | lists convert-to-text | Convert list items to plain paragraphs, optionally prepending the rendered marker text. |
Tables
| Operation | CLI command | Description |
|---|---|---|
doc.tables.convertFromText | tables convert-from-text | Convert a text range into a table. |
doc.tables.delete | tables delete | Delete the target table from the document. |
doc.tables.clearContents | tables clear-contents | Clear the contents of the target table or cell range. |
doc.tables.move | tables move | Move a table to a new position in the document. |
doc.tables.split | tables split | Split a table into two tables at the target row. |
doc.tables.convertToText | tables convert-to-text | Convert a table back to plain text. |
doc.tables.setLayout | tables set-layout | Set the layout mode of the target table. |
doc.tables.insertRow | tables insert-row | Insert a new row into the target table. |
doc.tables.deleteRow | tables delete-row | Delete a row from the target table. |
doc.tables.setRowHeight | tables set-row-height | Set the height of a table row. |
doc.tables.distributeRows | tables distribute-rows | Distribute row heights evenly across the target table. |
doc.tables.setRowOptions | tables set-row-options | Set options on a table row such as header repeat or page break. |
doc.tables.insertColumn | tables insert-column | Insert a new column into the target table. |
doc.tables.deleteColumn | tables delete-column | Delete a column from the target table. |
doc.tables.setColumnWidth | tables set-column-width | Set the width of a table column. |
doc.tables.distributeColumns | tables distribute-columns | Distribute column widths evenly across the target table. |
doc.tables.insertCell | tables insert-cell | Insert a new cell into a table row. |
doc.tables.deleteCell | tables delete-cell | Delete a cell from a table row. |
doc.tables.mergeCells | tables merge-cells | Merge a range of table cells into one. |
doc.tables.unmergeCells | tables unmerge-cells | Unmerge a previously merged table cell. |
doc.tables.splitCell | tables split-cell | Split a table cell into multiple cells. |
doc.tables.setCellProperties | tables set-cell-properties | Set properties on a table cell such as vertical alignment or text direction. |
doc.tables.sort | tables sort | Sort table rows by a column value. |
doc.tables.setAltText | tables set-alt-text | Set the alternative text description for a table. |
doc.tables.setStyle | tables set-style | Apply a named table style to the target table. |
doc.tables.clearStyle | tables clear-style | Remove the applied table style, reverting to defaults. |
doc.tables.setStyleOption | tables set-style-option | Toggle a conditional style option such as banded rows or first column. |
doc.tables.setBorder | tables set-border | Set border properties on a table or cell range. |
doc.tables.clearBorder | tables clear-border | Remove border formatting from a table or cell range. |
doc.tables.applyBorderPreset | tables apply-border-preset | Apply a border preset (e.g. all borders, outside only) to a table. |
doc.tables.setShading | tables set-shading | Set the background shading color on a table or cell range. |
doc.tables.clearShading | tables clear-shading | Remove shading from a table or cell range. |
doc.tables.setTablePadding | tables set-table-padding | Set default cell padding for the entire table. |
doc.tables.setCellPadding | tables set-cell-padding | Set padding on a specific table cell or cell range. |
doc.tables.setCellSpacing | tables set-cell-spacing | Set the cell spacing for the target table. |
doc.tables.clearCellSpacing | tables clear-cell-spacing | Remove custom cell spacing from the target table. |
doc.tables.get | tables get | Retrieve table structure and dimensions by locator. |
doc.tables.getCells | tables get-cells | Retrieve cell information for a table, optionally filtered by row or column. |
doc.tables.getProperties | tables get-properties | Retrieve layout and style properties of a table. |
doc.tables.getStyles | tables get-styles | List all table styles and the document-level default table style setting. |
doc.tables.setDefaultStyle | tables set-default-style | Set the document-level default table style (w:defaultTableStyle in settings.xml). |
doc.tables.clearDefaultStyle | tables clear-default-style | Remove the document-level default table style setting. |
Table of contents
| Operation | CLI command | Description |
|---|---|---|
doc.toc.list | toc list | List all tables of contents in the document. |
doc.toc.get | toc get | Retrieve details of a specific table of contents. |
doc.toc.configure | toc configure | Update the configuration switches of a table of contents. |
doc.toc.update | toc update | Rebuild or refresh the materialized content of a table of contents. |
doc.toc.remove | toc remove | Remove a table of contents from the document. |
doc.toc.markEntry | toc mark-entry | Insert a TC (table of contents entry) field at the target paragraph. |
doc.toc.unmarkEntry | toc unmark-entry | Remove a TC (table of contents entry) field from the document. |
doc.toc.listEntries | toc list-entries | List all TC (table of contents entry) fields in the document body. |
doc.toc.getEntry | toc get-entry | Retrieve details of a specific TC (table of contents entry) field. |
doc.toc.editEntry | toc edit-entry | Update the properties of a TC (table of contents entry) field. |
Comments
| Operation | CLI command | Description |
|---|---|---|
doc.comments.create | comments create | Create a new comment thread (or reply when parentCommentId is given). |
doc.comments.patch | comments patch | Patch fields on an existing comment (text, target, status, or isInternal). |
doc.comments.delete | comments delete | Remove a comment or reply by ID. |
doc.comments.get | comments get | Retrieve a single comment thread by ID. |
doc.comments.list | comments list | List all comment threads in the document. |
Track changes
| Operation | CLI command | Description |
|---|---|---|
doc.trackChanges.list | track-changes list | List all tracked changes in the document. |
doc.trackChanges.get | track-changes get | Retrieve a single tracked change by ID. |
doc.trackChanges.decide | track-changes decide | Accept or reject a tracked change (by ID or scope: all). |
Capabilities
| Operation | CLI command | Description |
|---|---|---|
doc.capabilities.get | capabilities | Query runtime capabilities supported by the current document engine. |
History
| Operation | CLI command | Description |
|---|---|---|
doc.history.get | history get | Query the current undo/redo history state of the active editor. |
doc.history.undo | history undo | Undo the most recent history-safe mutation in the active editor. |
doc.history.redo | history redo | Redo the most recently undone action in the active editor. |
Session
| Operation | CLI command | Description |
|---|---|---|
doc.session.list | session list | List all active editing sessions. |
doc.session.save | session save | Persist the current session state. |
doc.session.close | session close | Close a specific editing session by ID. |
doc.session.setDefault | session set-default | Set the default session for subsequent commands. |
Introspection
| Operation | CLI command | Description |
|---|---|---|
doc.status | status | Show the current session status and document metadata. |
doc.describe | describe | List all available CLI operations and contract metadata. |
doc.describeCommand | describe command | Show detailed metadata for a single CLI operation. |
Images
| Operation | CLI command | Description |
|---|---|---|
doc.images.list | images list | List all images in the document. |
doc.images.get | images get | Get details for a specific image by its stable ID. |
doc.images.delete | images delete | Delete an image from the document. |
doc.images.move | images move | Move an image to a new location in the document. |
doc.images.convertToInline | images convert-to-inline | Convert a floating image to inline placement. |
doc.images.convertToFloating | images convert-to-floating | Convert an inline image to floating placement. |
doc.images.setSize | images set-size | Set explicit width/height for an image. |
doc.images.setWrapType | images set-wrap-type | Set the text wrapping type for a floating image. |
doc.images.setWrapSide | images set-wrap-side | Set which side(s) text wraps around a floating image. |
doc.images.setWrapDistances | images set-wrap-distances | Set the text-wrap distance margins for a floating image. |
doc.images.setPosition | images set-position | Set the anchor position for a floating image. |
doc.images.setAnchorOptions | images set-anchor-options | Set anchor behavior options for a floating image. |
doc.images.setZOrder | images set-z-order | Set the z-order (relativeHeight) for a floating image. |
Related
- Document API — the in-browser API that defines the operation set
- CLI — use the same operations from the terminal
- Collaboration guides — set up Liveblocks, Hocuspocus, or SuperDoc Yjs

