Convert .docx via REST API

The DOCX document conversion API supports conversion from and to 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

The /v2/convert/import 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" \
    -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 "promisemirrorNodes={\"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 Collaboration settings page: 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, 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

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 "{\"paragraph\":\"textBlock\"}" 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

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

Export DOCX

POST /v2/convert/export

The /v2/convert/export endpoint converts Tiptap documents into DOCX format. Users can POST documents to this endpoint and use various parameters to customize how different document elements are handled during the conversion process.

Export customization support

The /v2/convert/export endpoint does not support custom node conversions as functions cannot be serialized, but it does support custom style overrides. If you wish to convert your documents on the server on your own premises to have this option available, you can follow the server side export guide.

Example (cURL)

curl --output example.docx -X POST https://api.tiptap.dev/v2/convert/export \
    -H "Authorization: Bearer <your-jwt-token>" \
    -H "X-App-Id: <your-app-id>" \
    -F 'doc={"type":"doc","content":[{"type":"paragraph","attrs":{"textAlign":"left"},"content":[{"type":"text","text":"Welcome to this demonstration of our editor'\''s ability to export a wide array of formatting options to DOCX, ensuring that your content retains its intended appearance in Word."}]}]}' \
    -F 'exportType=blob' \
    -F 'styleOverrides={}'

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 Collaboration settings page: https://cloud.tiptap.dev/convert-settings

Body

Name	Type	Description	Default
`doc`	`String`	Tiptap's JSON	`N/A`
`exportType`	`string`	The expected export type	`blob`
`styleOverrides`	`Object`	Style overrides	`{}`