---
title: "Legacy DOCX Import & Export"
description: "Review how to configure the legacy import and export extensions and REST API endpoints. More in the docs."
canonical_url: "https://tiptap.dev/docs/conversion/legacy/overview"
---

# Legacy DOCX Import & Export

Review how to configure the legacy import and export extensions and REST API endpoints. More in the docs.

The original `extension-import` and `extension-export` packages for Tiptap provide reliable methods to import and export DOCX files.

These extensions, and associated endpoints remain available to anyone with a Tiptap account but are deprecated and no longer actively developed.

They have been replaced by the new [Tiptap Conversion](https://tiptap.dev/docs/conversion/getting-started/overview.md) extensions and services.

> **Migrating from the legacy extensions:**
>
> See the [Migration guide](https://tiptap.dev/docs/conversion/legacy/migration-guide.md) for step-by-step instructions on
> moving to the format-specific Conversion extensions and the `/v2/` REST endpoints.

> **Default endpoint no longer hosted:**
>
> The legacy `extension-import` and `extension-export` packages default the `endpoint` option to
> `/v1/convert`, which the Conversion service no longer hosts. Existing integrations must either
> pass an explicit `endpoint: 'https://api.tiptap.dev/v2/convert'` (and accept the response-shape
> differences described below) or migrate to the format-specific Conversion extensions.

The following guide focuses on configuring the legacy extensions.

## Import legacy extension

> **Legacy Import Extension (Deprecated):**
>
> The **extension-import** package is deprecated and receives no new features; we
> will give 90 days' notice before removing the legacy endpoints. Please migrate to our [newer
> solutions](https://tiptap.dev/docs/conversion/getting-started/overview.md) to ensure uninterrupted service.

```js
// Start with importing the extension
import { Import } from '@tiptap-pro/extension-import'

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Import.configure({
      // The Convert App-ID from the Convert settings page: https://cloud.tiptap.dev/convert-settings
      appId: 'your-app-id',

      // The JWT you generated in the previous step
      token: 'your-jwt',

      // The URL to upload images to, if not provided, images will be stripped from the document
      imageUploadCallbackUrl: 'https://your-image-upload-url.com',

      // Enables the experimental DOCX import which should better preserve content styling
      experimentalDocxImport: true,
    }),
  ],
})
```

### Import your first document

```js
// The most simple way to import a file
// This will import the uploaded file, replace the editor content
// and focus the editor
editor.chain().focus().import({ file }).run()
```

#### Customize the import behavior

```js
// You can also use the onImport callback to customize the import behavior
editor
  .chain()
  .import({
    file,
    onImport(context) {
      const { setEditorContent, content, error } = context

      // add error handling
      if (error) {
        showErrorToast({ message: error.message })
      }

      // You could also modify the content before inserting it
      content.doc.content.push({ type: 'paragraph', content: [{ type: 'text', text: 'Hello!' }] })

      // you can change the loading state of your application for example
      isLoading = false

      // make sure you call the setEditorContent function if you want to run
      // the default insertion behavior of the extension
      // setEditorContent()
      // but since we modified the content, we need to do the insertion manually
      editor.commands.setContent(content)
    },
  })
  .focus()
  .run()
```

### Import options

| Name                     | Type       | Default     | Description                                                                                                                                                                                     |
| ------------------------ | ---------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appId`                  | `string`   | `undefined` | The convert app ID from the Convert settings page: [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings)                                                       |
| `token`                  | `string`   | `undefined` | The JWT generated from your server via secret                                                                                                                                                   |
| `imageUploadCallbackUrl` | `string`   | `undefined` | The URL to upload images to, if not provided, images will be stripped from the document                                                                                                         |
| `experimentalDocxImport` | `boolean ` | `false`     | Enables the experimental DOCX import which should better preserve content styling (experimental, and this API may not be completely stable while in alpha), only applies to DOCX files uploaded |

### Commands

| Name     | Description                   |
| -------- | ----------------------------- |
| `import` | Import a file into the editor |

#### `import`

##### Arguments

| Name       | Type       | Default     | Options       | Description                                                                                                                                                                   |
| ---------- | ---------- | ----------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`     | `File`     | `undefined` | Any file      | The file to import                                                                                                                                                            |
| `format`   | `string`   | `undefined` | `gfm`         | Is used for special cases where the format is not clear, for example markdown gfm                                                                                             |
| `onImport` | `Function` | `undefined` | `fn(context)` | A callback used to customize the import behavior. The context argument includes information about the content, errors and a `setEditorContent` function to modify the content |

### Supported formats

- `docx` - Microsoft Word, Google Docs, OpenOffice, LibreOffice and others
- `odt` - OpenDocument Text format used by OpenOffice, LibreOffice and others
- `rtf` - Rich Text Format used by Microsoft Word, Google Docs and others
- Commonmark `markdown` - Markdown format used by various editors and platforms
- GFM `markdown` - GitHub Flavored Markdown used by GitHub

### Caveats and limitations

- **Image upload** - Images are assumed to be inline within the document so, your editor should be setup with `Image.configure({ inline: true })` to display them correctly, otherwise they will be stripped from the document
- **Unsupported docx elements on import** - Importing docx files currently does not support page breaks, page headers and footers, horizontal rules or text styles
- **Content added via suggestion mode** - Content added via suggestion mode is not included in the imported ProseMirror document
- **PDF import & export** - Importing and exporting PDF files is not yet supported
- **Inline styles** - Inline styles are currently not parsed and are not available in import & export

## Export legacy extension

> **Legacy Export Extension (Deprecated):**
>
> The **extension-export** package is deprecated and receives no new features; we
> will give 90 days' notice before removing the legacy endpoints. We strongly recommend
> transitioning to our updated [export extension](https://tiptap.dev/docs/conversion/getting-started/overview.md), which
> offers improved customization and ongoing support.

```js
// Start with importing the extension
import { Export } from '@tiptap-pro/extension-export'

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Export.configure({
      // The Convert App-ID from the convert settings page: https://cloud.tiptap.dev/convert-settings
      appId: 'your-app-id',

      // The JWT you generated in the previous step
      token: 'your-jwt',
    }),
  ],
})
```

### Export a document

```js
// Do a simple export to docx
// Supported formats: docx, odt, md and gfm
editor.chain().focus().export({ format: 'docx' }).run()
```

### Customize the export behavior

```js
// You can also use the onExport callback to customize the export behavior
editor.chain().export({
  format: 'docx',
  onExport(context) {
    const { blob, error, download, filename } = context

    // add error handling
    if (error) {
      showErrorToast({ message: error.message })
    }

    // you can change the loading state of your application for example
    isLoading = false

    // you could modify the filename or handle the blob differently here
    // but we will keep them as they are

    // you can trigger a download directly by calling the download method
    download()

    // keep in mind that the download method will only work in the browser
    // and if the blob and filename was changed before must be managed manually
  },
})
```

### Export options

| Name    | Type     | Default     | Description                                                                                                                               |
| ------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `appId` | `string` | `undefined` | The convert app ID from the Convert settings page: [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |
| `token` | `string` | `undefined` | The JWT generated from your server via secret                                                                                             |

### Commands

| Name     | Description               |
| -------- | ------------------------- |
| `export` | Export the editor content |

#### `export`

##### Arguments

| Name       | Type          | Default     | Options           | Description                                                                                                                                                                              |
| ---------- | ------------- | ----------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `format`   | `string`      | `undefined` | `docx,odt,md,gfm` | The format you want to export to                                                                                                                                                         |
| `content`  | `JSONContent` | `undefined` | Any Tiptap JSON   | The Tiptap JSON content you want to export                                                                                                                                               |
| `onExport` | `Function`    | `undefined` | `fn(context)`     | A callback used to customize the export behavior. The context argument includes information about the blob, filename, errors and a `download` function to download the document directly |

### Supported formats

- `docx` - Microsoft Word, Google Docs, OpenOffice, LibreOffice and others
- `odt` - OpenDocument Text format used by OpenOffice, LibreOffice and others
- Commonmark `markdown` - Markdown format used by various editors and platforms
- GFM `markdown` - GitHub Flavored Markdown used by GitHub

### Caveats and limitations

- **Custom Node exports** - Exporting custom nodes or marks is supported in the new [Conversion](https://tiptap.dev/docs/conversion/getting-started/overview.md) extensions and endpoints.
- **Custom docx templates** - Review our new [Conversion](https://tiptap.dev/docs/conversion/getting-started/overview.md) extensions and endpoints to integrate docx templates.
- **PDF import & export** - Exporting PDF files is not yet supported
- **Inline styles** - Review our new [Conversion](https://tiptap.dev/docs/conversion/getting-started/overview.md) extensions and endpoints to integrate inline styles.

## Legacy REST API

> **Legacy /v1/ Conversion REST API (Deprecated):**
>
> The **/v1/ Document Conversion REST API** is deprecated and receives no new
> features; we will give 90 days' notice before removing the legacy endpoints. For continued updates
> and maintenance, migrate to newer [API endpoints](https://tiptap.dev/docs/conversion/getting-started/overview.md) or check
> out our [Postman
> Collection](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-bcc93ecb-8bad-4484-8cb0-d995ee23ae60)
> for the latest resources.

The legacy document conversion API supports DOCX, ODT, and Markdown conversion from and to Tiptap's JSON format.

### /import endpoint

The `/import` endpoint enables the conversion of `docx`, `odt`, or `markdown` files into Tiptap's JSON format. Users can POST documents to this endpoint and use various parameters to customize how different document elements are handled during the conversion process.

- **Method**: `POST`

#### Required headers

| Name            | Description                                                                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | The JWT to authenticate the request. Example: `Bearer your-jwt`                                                                                 |
| `X-App-Id`      | The Convert App-ID from the Collaboration settings page: [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |

#### Body

| Name                     | Type     | Description                                                                               |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------- |
| `file`                   | `File`   | The file to convert                                                                       |
| `imageUploadCallbackUrl` | `string` | The callback endpoint to upload images that were encountered within the uploaded document |

#### Query parameters

Specify how source document elements are mapped to ProseMirror nodes or marks, and adjust the conversion to meet your specific styling and structural preferences.

| Name             | Default          | Description                                                          |
| ---------------- | ---------------- | -------------------------------------------------------------------- |
| `paragraph`      | `paragraph`      | Defines which ProseMirror type is used for paragraph conversion      |
| `heading`        | `heading`        | Defines which ProseMirror type is used for heading conversion        |
| `blockquote`     | `blockquote`     | Defines which ProseMirror type is used for blockquote conversion     |
| `codeblock`      | `codeblock`      | Defines which ProseMirror type is used for codeblock conversion      |
| `bulletlist`     | `bulletlist`     | Defines which ProseMirror type is used for bulletList conversion     |
| `orderedlist`    | `orderedlist`    | Defines which ProseMirror type is used for orderedList conversion    |
| `listitem`       | `listitem`       | Defines which ProseMirror type is used for listItem conversion       |
| `hardbreak`      | `hardbreak`      | Defines which ProseMirror type is used for hardbreak conversion      |
| `horizontalrule` | `horizontalrule` | Defines which ProseMirror type is used for horizontalRule conversion |
| `table`          | `table`          | Defines which ProseMirror type is used for table conversion          |
| `tablecell`      | `tablecell`      | Defines which ProseMirror type is used for tableCell conversion      |
| `tableheader`    | `tableheader`    | Defines which ProseMirror type is used for tableHeader conversion    |
| `tablerow`       | `tablerow`       | Defines which ProseMirror type is used for tableRow conversion       |
| `bold`           | `bold`           | Defines which ProseMirror mark is used for bold conversion           |
| `italic`         | `italic`         | Defines which ProseMirror mark is used for italic conversion         |
| `underline`      | `underline`      | Defines which ProseMirror mark is used for underline conversion      |
| `strikethrough`  | `strike`         | Defines which ProseMirror mark is used for strikethrough conversion  |
| `link`           | `link`           | Defines which ProseMirror mark is used for link conversion           |
| `code`           | `code`           | Defines which ProseMirror mark is used for code conversion           |
| `image`          | `image`          | Defines which ProseMirror mark is used for image conversion          |

### /import-docx endpoint (experimental)

The `/import-docx` endpoint enables the conversion of docx files into Tiptap's JSON format and allows for more docx-specific functions than the /import endpoint. Users can POST documents to this endpoint and use various parameters to customize how different document elements are handled during the conversion process.

- **Method**: `POST`

#### Required headers

| Name            | Description                                                                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | The JWT to authenticate the request. Example: `Bearer your-jwt`                                                                                 |
| `X-App-Id`      | The Convert App-ID from the Collaboration settings page: [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |

#### Body

| Name                     | Type     | Description                                                                               |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------- |
| `file`                   | `File`   | The file to convert                                                                       |
| `imageUploadCallbackUrl` | `string` | The callback endpoint to upload images that were encountered within the uploaded document |

#### Query parameters

Specify how source document elements are mapped to ProseMirror nodes or marks, and adjust the conversion to meet your specific styling and structural preferences.

| Name             | Default          | Description                                                          |
| ---------------- | ---------------- | -------------------------------------------------------------------- |
| `paragraph`      | `paragraph`      | Defines which ProseMirror type is used for paragraph conversion      |
| `heading`        | `heading`        | Defines which ProseMirror type is used for heading conversion        |
| `blockquote`     | `blockquote`     | Defines which ProseMirror type is used for blockquote conversion     |
| `codeblock`      | `codeblock`      | Defines which ProseMirror type is used for codeblock conversion      |
| `bulletlist`     | `bulletlist`     | Defines which ProseMirror type is used for bulletList conversion     |
| `orderedlist`    | `orderedlist`    | Defines which ProseMirror type is used for orderedList conversion    |
| `listitem`       | `listitem`       | Defines which ProseMirror type is used for listItem conversion       |
| `hardbreak`      | `hardbreak`      | Defines which ProseMirror type is used for hardbreak conversion      |
| `horizontalrule` | `horizontalrule` | Defines which ProseMirror type is used for horizontalRule conversion |
| `table`          | `table`          | Defines which ProseMirror type is used for table conversion          |
| `tablecell`      | `tablecell`      | Defines which ProseMirror type is used for tableCell conversion      |
| `tableheader`    | `tableheader`    | Defines which ProseMirror type is used for tableHeader conversion    |
| `tablerow`       | `tablerow`       | Defines which ProseMirror type is used for tableRow conversion       |
| `bold`           | `bold`           | Defines which ProseMirror mark is used for bold conversion           |
| `italic`         | `italic`         | Defines which ProseMirror mark is used for italic conversion         |
| `underline`      | `underline`      | Defines which ProseMirror mark is used for underline conversion      |
| `strikethrough`  | `strike`         | Defines which ProseMirror mark is used for strikethrough conversion  |
| `link`           | `link`           | Defines which ProseMirror mark is used for link conversion           |
| `code`           | `code`           | Defines which ProseMirror mark is used for code conversion           |
| `image`          | `image`          | Defines which ProseMirror mark is used for image conversion          |

### /export endpoint

The `/export` endpoint converts Tiptap documents back into formats like `docx`, `odt`, or `markdown`.

- **Method**: `POST`

Convert a Tiptap document to a different format.

#### Required headers

| Name            | Description                                                                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | The JWT to authenticate the request. Example: `Bearer your-jwt`                                                                                 |
| `X-App-Id`      | The Convert App-ID from the Collaboration settings page: [https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |

#### Body

| Name      | Type     | Description                                                  |
| --------- | -------- | ------------------------------------------------------------ |
| `content` | `Object` | The Tiptap document                                          |
| `format`  | `string` | The format to convert to, can be `docx`, `odt` or `markdown` |

#### Query parameters

| Name             | Default          | Description                                                          |
| ---------------- | ---------------- | -------------------------------------------------------------------- |
| `gfm`            | `0`              | Use Github Flavored Markdown for markdown export                     |
| `paragraph`      | `paragraph`      | Defines which ProseMirror type is used for paragraph conversion      |
| `heading`        | `heading`        | Defines which ProseMirror type is used for heading conversion        |
| `blockquote`     | `blockquote`     | Defines which ProseMirror type is used for blockquote conversion     |
| `codeblock`      | `codeblock`      | Defines which ProseMirror type is used for codeblock conversion      |
| `bulletlist`     | `bulletlist`     | Defines which ProseMirror type is used for bulletList conversion     |
| `orderedlist`    | `orderedlist`    | Defines which ProseMirror type is used for orderedList conversion    |
| `listitem`       | `listitem`       | Defines which ProseMirror type is used for listItem conversion       |
| `hardbreak`      | `hardbreak`      | Defines which ProseMirror type is used for hardbreak conversion      |
| `horizontalrule` | `horizontalrule` | Defines which ProseMirror type is used for horizontalRule conversion |
| `table`          | `table`          | Defines which ProseMirror type is used for table conversion          |
| `tablecell`      | `tablecell`      | Defines which ProseMirror type is used for tableCell conversion      |
| `tableheader`    | `tableheader`    | Defines which ProseMirror type is used for tableHeader conversion    |
| `tablerow`       | `tablerow`       | Defines which ProseMirror type is used for tableRow conversion       |
| `bold`           | `bold`           | Defines which ProseMirror mark is used for bold conversion           |
| `italic`         | `italic`         | Defines which ProseMirror mark is used for italic conversion         |
| `underline`      | `underline`      | Defines which ProseMirror mark is used for underline conversion      |
| `strikethrough`  | `strike`         | Defines which ProseMirror mark is used for strikethrough conversion  |
| `link`           | `link`           | Defines which ProseMirror mark is used for link conversion           |
| `code`           | `code`           | Defines which ProseMirror mark is used for code conversion           |