> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autype.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DOCX roundtrip

> Import an editable Word document as validated Autype JSON and render it back to DOCX

Autype can use an existing Word document as the starting point for an API or
agent workflow:

```text theme={null}
DOCX -> validated Autype Document JSON -> edit -> render -> DOCX
```

The importer reads ordered OOXML directly. It does not convert Word to HTML
first. Supported content remains editable, and every normalization is returned
as a structured diagnostic.

## Direct API import

Send a DOCX as multipart form data:

```bash theme={null}
curl -X POST "https://api.autype.com/api/v1/dev/import/docx" \
  -H "X-API-Key: ak_your_api_key" \
  -F "file=@contract.docx"
```

The response contains a complete `document` object accepted by
`POST /api/v1/dev/render`. Keep `document.document.type` set to `docx` for the
Word output.

## File and MCP workflow

For an MCP client or a reusable toolkit upload:

1. Upload the source with `files_upload` or `POST /api/v1/dev/tools/files/upload`.
2. Call `docx_import` or `POST /api/v1/dev/import/docx/file` with its `fileId`.
3. Edit the returned Document JSON.
4. Call `render_json` to produce a temporary DOCX, or create a persistent
   document with the JSON and render that document.

Embedded raster images become protected temporary image references in the
Developer API flow. They remain usable for 24 hours and are promoted to
permanent organization-protected assets when the JSON is saved as a persistent
document.

## Preserved and normalized content

The importer preserves body order, headings and bookmarks, paragraphs,
supported inline formatting, links, nested lists, tables, content controls,
TOC fields, page and section breaks, page size/orientation/margins, columns,
page-number settings, metadata, headers/footers, and embedded PNG/JPEG/GIF/WebP
images. Native Word footnotes remain editable Autype footnotes and are emitted
as native Word footnotes on DOCX export. Autype-generated charts, canvases, QR codes, and other visual elements
already stored in Word as raster images roundtrip as ordinary `image` elements.

Word features without a lossless Autype equivalent are normalized safely. For
example, merged table cells are expanded into an editable rectangular grid,
multiple header/footer variants use their default variant, and unsupported or
active content is ignored. Native Word equations remain editable as normalized
math text. Native charts, diagrams, and embedded objects use their embedded
image preview when one exists; otherwise the missing preview is reported
explicitly rather than silently inventing content. Endnotes and comments do not
currently have a lossless Autype representation and therefore produce an
explicit `partial` diagnostic instead of disappearing silently. The response
reports all of these cases in:

* `warnings`: concise human-readable messages
* `diagnostics`: codes, severity, OOXML part, fallback and path where available
* `quality`: `exact`, `normalized`, or `partial` for content, styling, and layout

<Warning>
  An arbitrary Word document is not promised to reproduce pixel-for-pixel.
  Content remains editable wherever the Autype schema has an equivalent; visual
  or proprietary constructs are retained as images when the DOCX contains an
  embedded image representation.
</Warning>

## Limits and security

* Maximum upload size: 50 MB
* Maximum ZIP entries: 5,000
* Maximum uncompressed package size: 200 MB
* Maximum uncompressed part size: 50 MB
* XML DTD and entity declarations are rejected
* ZIP traversal, invalid signatures, and external image fetching are rejected
* `manage:files` is required for Developer API and MCP imports
* Imported images never expose a public object-storage URL