Import DOCX via REST API

Available in Start planBetav2.8.0

The DOCX import API converts .docx files into Tiptap's JSON format.

Review the postman collection

You can also experiment with the Document Conversion API by heading over to our Postman Collection.

Import DOCX

POST /v2/convert/import/docx

The /v2/convert/import/docx endpoint converts docx 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.

Example (cURL)

curl -X POST "https://api.tiptap.dev/v2/convert/import/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -F "file=@/path/to/your/file.docx" \
    -F "imageUploadCallbackUrl=https://your-image-upload-endpoint.com" \
    -F "prosemirrorNodes={\"nodeKey\":\"nodeValue\"}" \
    -F "prosemirrorMarks={\"markKey\":\"markValue\"}"

Subscription required

This endpoint requires a valid Tiptap subscription. For more details review our pricing page.

Required headers

Name	Description
`Authorization`	The JWT token to authenticate the request. Example: `Bearer your-jwt-token`
`X-App-Id`	The Convert App-ID from the Convert settings page: https://cloud.tiptap.dev/v2/cloud/convert

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, see more info
`prosemirrorNodes`	`Object string`	Custom node mapping for the conversion, see more info.
`prosemirrorMarks`	`Object string`	Custom mark mapping for the conversion, see more info
`verbose`	`string \| number`	A configuration property to help you control the level of diagnostic output during the import process. This is especially useful for debugging or for getting more insight into what happens during conversion. See more at Verbose output

Import verbose output

The DOCX import extension provides a verbose configuration property to help you control the level of diagnostic output during the import process. This is especially useful for debugging or for getting more insight into what happens during conversion.

The verbose property is a bitmask number that determines which types of log messages are emitted. The extension uses the following levels:

Value	Level	Description
1	`log`	General informational logs
2	`warn`	Warnings
4	`error`	Errors

Verbose bitmask

You can combine levels by adding their values together. For example, verbose: 3 will enable both log (1) and warn (2) messages.

The verbose output will give you, along the data property, one more property called logs, which will contain info, warn, and error properties, each of them being an array with all of the information related to that specific verbosity.

{
  "data": {
    "content": {
        // Tiptap JSON
    }
  },
  "logs": {
    "info": [],
    "warn": [
      {
        "message": "Image file not found in media files",
        "fileName": "image1.gif",
        "availableMediaFiles": []
      }
    ],
    "error": [
      {
        "message": "Image upload failed: General error",
        "fileName": "image1.gif",
        "url": "https://your-image-upload-endpoint.com",
        "error": "Unable to connect. Is the computer able to access the url?",
        "context": "uploadImage general error"
      }
    ]
  }
}

Headers & Footers in the response

The import API extracts headers and footers from .docx files. When the document contains header or footer content, additional fields are included in the data object of the response.

Response fields

Field	Type	Description
`content`	`Object`	The main document body as Tiptap JSON
`header`	`Object \| null`	Default header content as Tiptap JSON
`footer`	`Object \| null`	Default footer content as Tiptap JSON
`headerFirstPage`	`Object \| null`	First page header (when "Different First Page" is enabled in Word)
`footerFirstPage`	`Object \| null`	First page footer (when "Different First Page" is enabled in Word)
`headerOdd`	`Object \| null`	Odd page header (when "Different Odd & Even Pages" is enabled in Word)
`footerOdd`	`Object \| null`	Odd page footer (when "Different Odd & Even Pages" is enabled in Word)
`headerEven`	`Object \| null`	Even page header (when "Different Odd & Even Pages" is enabled in Word)
`footerEven`	`Object \| null`	Even page footer (when "Different Odd & Even Pages" is enabled in Word)

Example response

{
  "data": {
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "Document body content..." }]
        }
      ]
    },
    "header": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "Default Header" }]
        }
      ]
    },
    "footer": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "Page {page} of {total}" }]
        }
      ]
    },
    "headerFirstPage": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Title Page Header",
              "marks": [{ "type": "bold" }]
            }
          ]
        }
      ]
    },
    "footerFirstPage": null,
    "headerOdd": null,
    "footerOdd": null,
    "headerEven": null,
    "footerEven": null
  }
}

Fields that are null indicate the document does not define content for that specific header or footer slot.

Footnotes & Endnotes in the response

The import API extracts footnotes and endnotes from .docx files. When the document contains footnote or endnote content, additional fields are included in the data object of the response.

Response fields

Field	Type	Description
`footnotes`	`Object`	An object keyed by footnote ID, where each value is a Tiptap JSON document (`{ type: "doc", content: [...] }`)
`endnotes`	`Object`	An object keyed by endnote ID, where each value is a Tiptap JSON document (`{ type: "doc", content: [...] }`)

Documents without footnotes or endnotes return empty objects ({}), so existing integrations are unaffected.

Inline references in the document body are represented as footnoteReference and endnoteReference nodes, each carrying a noteId attribute that links to the corresponding entry in footnotes or endnotes.

Example response

{
  "data": {
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            { "type": "text", "text": "This sentence has a footnote" },
            { "type": "footnoteReference", "attrs": { "noteId": "1" } },
            { "type": "text", "text": " and an endnote" },
            { "type": "endnoteReference", "attrs": { "noteId": "1" } },
            { "type": "text", "text": "." }
          ]
        }
      ]
    },
    "footnotes": {
      "1": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [{ "type": "text", "text": "This is the footnote content." }]
          }
        ]
      }
    },
    "endnotes": {
      "1": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [{ "type": "text", "text": "This is the endnote content." }]
          }
        ]
      }
    },
    "header": null,
    "footer": null,
    "headerFirstPage": null,
    "footerFirstPage": null,
    "headerOdd": null,
    "footerOdd": null,
    "headerEven": null,
    "footerEven": null
  }
}

Custom node and mark mapping

You can override the default node/mark types used during import by specifying them in the body of your request within prosemirrorNodes and prosemirrorMarks respectively. You would need to provide these if your editor uses custom nodes/marks and you want the imported JSON to use those.

For example, if your schema uses a custom node type called textBlock instead of the default paragraph, you can include "{\"textBlock\":\"paragraph\"}" in the request body.

You can similarly adjust headings, lists, marks like bold or italic, and more.

Default nodes

Name	Description
`paragraph`	Defines which ProseMirror type is used for paragraph conversion
`heading`	Defines which ProseMirror type is used for heading conversion
`blockquote`	Defines which ProseMirror type is used for blockquote conversion
`codeblock`	Defines which ProseMirror type is used for codeblock conversion
`bulletlist`	Defines which ProseMirror type is used for bulletList conversion
`orderedlist`	Defines which ProseMirror type is used for orderedList conversion
`listitem`	Defines which ProseMirror type is used for listItem conversion
`hardbreak`	Defines which ProseMirror type is used for hardbreak conversion
`horizontalrule`	Defines which ProseMirror type is used for horizontalRule conversion
`table`	Defines which ProseMirror type is used for table conversion
`tablecell`	Defines which ProseMirror type is used for tableCell conversion
`tableheader`	Defines which ProseMirror type is used for tableHeader conversion
`tablerow`	Defines which ProseMirror type is used for tableRow conversion
`image`	Defines which ProseMirror mark is used for image conversion
`footnoteReference`	Defines which ProseMirror type is used for footnote reference conversion
`endnoteReference`	Defines which ProseMirror type is used for endnote reference conversion

Default marks

Name	Description
`bold`	Defines which ProseMirror mark is used for bold conversion
`italic`	Defines which ProseMirror mark is used for italic conversion
`underline`	Defines which ProseMirror mark is used for underline conversion
`strikethrough`	Defines which ProseMirror mark is used for strikethrough conversion
`link`	Defines which ProseMirror mark is used for link conversion
`code`	Defines which ProseMirror mark is used for code conversion

Support & Limitations

Currently supported features and known limitations for DOCX import:

Feature	Support
Text content	✓ Basic text, spacing, punctuation
Text formatting	✓ Bold, italic, underline, strikethrough, alignment, line height
Block elements	✓ Paragraphs, headings (1–6), blockquotes, ordered and unordered lists
Tables	✓ Basic structure, header rows, colspan
Links	✓ Hyperlinks
Media (Images)	✓ Embedded images, size preserved
Styles	✓ Font families*, Font colors, font sizes, background colors, line heights
Headers & Footers	✓ Supported (requires Pages extension)
Sections & Page Breaks	~ In development
Footnotes & Endnotes	✓ Supported
Math	~ In development
Comments & Revisions	✗
Table of Contents	✗
Advanced Formatting	✗ Columns, text direction, forms, macros, embedded scripts
Metadata	✗
Text Boxes, Shapes, SmartArt	✗

* Font families are supported as long as the target font is installed on the operative system when the .docx file is opened.

PreviouslyPreserve images

Next upMarkdown