Skip to main content

​
Workflow

Every interaction follows the same pattern: open, read or edit, save, close.
  1. superdoc_open loads a .docx file and returns a session_id
  2. superdoc_get_content reads the current document and superdoc_search finds stable handles or addresses
  3. Intent tools use session_id plus action to edit, format, create, comment, review track changes, or run batched mutations
  4. superdoc_save writes changes to disk
  5. superdoc_close releases the session

​
Efficient patterns

​
Create multiple sections at once

Use superdoc_edit with type: "markdown" to insert structured content in a single call. It parses markdown into proper document nodes: headings, paragraphs, bold, italic, and lists.
Markdown syntax maps to document styles:

​
Format multiple items at once

Use superdoc_mutations with format.apply steps to apply formatting across the document in one atomic call.
Format targets must exist before the batch runs. Node selectors resolve at step execution time using the current document state. If a required target is missing, the step fails and: with atomic: true: the entire batch rolls back.

​
When to use which tool

​
Targeting

Every editing tool needs a target telling the API where to apply the change. There are three ways to get one:
  • From blocks data: Each block has a ref (pass to superdoc_edit or superdoc_format) and a nodeId (for building at positions with superdoc_create).
  • From superdoc_search: Returns handle.ref covering the matched text. Use search when you need to find text patterns, not when you already know which block to target.
  • From superdoc_create: Returns nodeId and ref for the new node. For creating multiple sections or blocks at once, prefer superdoc_edit with type: "markdown" instead of multiple superdoc_create calls. Re-fetch blocks after create to get a fresh ref before formatting.
Refs expire after any mutation. Always re-search or re-read blocks before the next operation. Within a superdoc_mutations batch, node selectors resolve automatically at step execution time, so re-fetching between steps is not required.

​
Common operations

​
Replace text everywhere

​
Rewrite a paragraph

A block ref covers the entire block text. A search ref covers only the matched substring. Use block refs when rewriting whole paragraphs.

​
Add content after a heading

​
Format text

​
Create a list

Create paragraphs first, then convert:

​
Batch edits atomically

Use superdoc_mutations when you need multiple changes that must succeed or fail together. Supported step types include text.rewrite, text.delete, format.apply, create.heading, create.paragraph, and create.table.

​
Tracked changes

Actions that support tracked edits use the underlying Document API’s changeMode: "tracked" option. Review or resolve tracked edits with superdoc_track_changes:

​
Tips

  • Format calls must be sequential. Each call invalidates all outstanding refs. Format one block, re-fetch, then format the next.
  • Search patterns are plain text. Do not include markdown markers like # or **.
  • Pass structured objects, not JSON strings. Fields like at, target, and inline expect objects.
  • On a blank document, omit positional at on the first superdoc_create. Then fetch blocks for nodeIds before subsequent inserts.