superdoc-sdk

Programmatic SDK for deterministic DOCX operations through SuperDoc's Document API.

Alpha — The API surface matches the Document API and will evolve alongside it.

Install

pip install superdoc-sdk

The CLI is bundled with the SDK — no separate install needed. A platform-specific CLI companion package is installed automatically via PEP 508 environment markers.

Quick start

import asyncio

from superdoc import AsyncSuperDocClient


async def main():
    async with AsyncSuperDocClient(default_change_mode="tracked") as client:
        # Open a document
        doc = await client.open({"doc": "./contract.docx"})

        # Find and replace text with query + mutation plan
        match = await doc.query.match(
            {
                "select": {"type": "text", "pattern": "ACME Corp"},
                "require": "first",
            }
        )

        items = match.get("items") or []
        first_item = items[0] if items else {}
        ref = first_item.get("handle", {}).get("ref")
        if ref:
            await doc.mutations.apply(
                {
                    "expectedRevision": match["evaluatedRevision"],
                    "atomic": True,
                    "steps": [
                        {
                            "id": "replace-acme",
                            "op": "text.rewrite",
                            "where": {"by": "ref", "ref": ref},
                            "args": {"replacement": {"text": "NewCo Inc."}},
                        }
                    ],
                }
            )

        # Save and close
        await doc.save({"inPlace": True})
        await doc.close({})


asyncio.run(main())

Set default_change_mode="tracked" to make mutations use tracked changes by default. If you pass changeMode on a specific call, that explicit value overrides the default.

The SDK also exposes a synchronous SuperDocClient with the same document-handle methods when you prefer non-async code paths.

Encrypted documents

Pass password when opening a password-protected .docx:

doc = await client.open({"doc": "./secret.docx", "password": "mypassword"})

The password is forwarded only for the initial open and is not persisted. If the password is missing or wrong, the error includes a machine-readable code (DOCX_PASSWORD_REQUIRED, DOCX_PASSWORD_INVALID).

Sync

from superdoc import SuperDocClient

with SuperDocClient() as client:
    doc = client.open({"doc": "./contract.docx"})

    info = doc.info({})
    print(info["counts"])

    doc.save({"inPlace": True})
    doc.close({})

User identity

By default the SDK attributes edits to a generic "CLI" user. Set user on the client to identify your automation in comments, tracked changes, and collaboration presence:

client = AsyncSuperDocClient(user={"name": "Review Bot", "email": "bot@example.com"})

The user is injected into every client.open call. If you pass userName or userEmail on a specific client.open, those per-call values take precedence.

Client lifecycle

The SDK uses a persistent host process for all operations. The host is started on first use and reused across calls, avoiding per-operation subprocess overhead.

Context managers (recommended)

# Sync
with SuperDocClient() as client:
    doc = client.open({"doc": "./test.docx"})
    doc.find({"query": "test"})

# Async
async with AsyncSuperDocClient() as client:
    doc = await client.open({"doc": "./test.docx"})
    await doc.find({"query": "test"})

The context manager calls connect() on entry and dispose() on exit (including on exception).

Explicit lifecycle

client = SuperDocClient()
client.connect()      # Optional — first invoke() auto-connects
doc = client.open({"doc": "./test.docx"})
result = doc.find({"query": "test"})
client.dispose()      # Shuts down the host process

connect() is optional. If not called explicitly, the first operation triggers a lazy connection to the host process.

Configuration

client = SuperDocClient(
    startup_timeout_ms=10_000,    # Max time for host handshake (default: 5000)
    shutdown_timeout_ms=5_000,    # Max time for graceful shutdown (default: 5000)
    request_timeout_ms=60_000,    # Per-operation timeout passed to CLI (default: None)
    watchdog_timeout_ms=30_000,   # Client-side safety timer per request (default: 30000)
    default_change_mode="tracked", # Auto-inject changeMode for mutations (default: None)
    user={"name": "Bot", "email": "bot@example.com"},  # User identity for attribution
    env={"SUPERDOC_CLI_BIN": "/path/to/superdoc"},  # Environment overrides
)

Thread safety

Client instances are serialized: one operation at a time per client. For parallelism, use multiple client instances. Do not share a single client across threads.

Collaboration sessions

Use this when your app already has a live collaboration room. The SDK supports y-websocket, hocuspocus, and liveblocks providers. See the full collaboration docs for provider choice guidance and all configuration options.

Join an existing room (y-websocket shorthand)

The collabUrl + collabDocumentId shorthand defaults to the y-websocket provider. For Hocuspocus or Liveblocks, pass an explicit collaboration object.

import asyncio

from superdoc import AsyncSuperDocClient


async def main():
    async with AsyncSuperDocClient() as client:
        doc = await client.open({
            "collabUrl": "ws://localhost:4000",
            "collabDocumentId": "my-doc-room",
        })

        await doc.insert({
            "target": {"type": "end"},
            "content": "Added by the SDK",
        })


asyncio.run(main())

Connect to Hocuspocus explicitly

doc = await client.open({
    "collaboration": {
        "providerType": "hocuspocus",
        "url": "ws://localhost:1234",
        "documentId": "my-doc-room",
    }
})

Connect to Liveblocks

# Public API key
doc = await client.open({
    "collaboration": {
        "providerType": "liveblocks",
        "roomId": "my-room",
        "publicApiKey": "pk_live_xxx",
    }
})

# Auth endpoint (production)
doc = await client.open({
    "collaboration": {
        "providerType": "liveblocks",
        "roomId": "my-room",
        "authEndpoint": "https://app.example.com/api/liveblocks-auth",
    }
})

SDK authEndpoint values must be absolute URLs. Relative paths like /api/liveblocks-auth are not supported because the CLI host has no browser origin.

Start an empty room from a local .docx

doc = await client.open({
    "doc": "./starting-template.docx",
    "collabUrl": "ws://localhost:4000",
    "collabDocumentId": "my-doc-room",
})

Control empty-room behavior

If you only want to join rooms that already exist, use onMissing: 'error':

doc = await client.open({
    "collabUrl": "ws://localhost:4000",
    "collabDocumentId": "my-doc-room",
    "onMissing": "error",
})

Check if the SDK seeded or joined

doc = await client.open({
    "doc": "./starting-template.docx",
    "collabUrl": "ws://localhost:4000",
    "collabDocumentId": "my-doc-room",
})

print(doc.open_result.get("bootstrap"))
# { roomState, bootstrapApplied, bootstrapSource }

Available operations

The SDK exposes all document-handle operations from the Document API plus client lifecycle and introspection methods.

Lifecycle

Query

Mutation

Format

And 30+ additional formatting operations (letter spacing, vertical alignment, small caps, shading, borders, and more).

Create

Blocks

Lists

Comments

Track changes

History

Client methods

Troubleshooting

Custom CLI binary

If you need to use a custom-built CLI binary (e.g. a newer version or a patched build), set the SUPERDOC_CLI_BIN environment variable:

export SUPERDOC_CLI_BIN=/path/to/superdoc

Debug logging

Enable transport-level debug logging to diagnose connectivity issues:

export SUPERDOC_DEBUG=1

Air-gapped / private index environments

Mirror both superdoc-sdk and the superdoc-sdk-cli-* package for your platform to your private index. For example, on macOS ARM64:

pip download superdoc-sdk superdoc-sdk-cli-darwin-arm64
# Upload both wheels to your private index

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

Part of SuperDoc

This SDK is part of SuperDoc — open-source DOCX editing and tooling. Renders, edits, and automates .docx in the browser and on the server.

License

AGPL-3.0 · Enterprise license available