Convert .docx via REST API

Available in Start planBeta

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
`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"
      }
    ]
  }
}

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'

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	`{}`
`pageSize`	`Object`	Page size configuration	`undefined`
`pageMargins`	`Object`	Page margins configuration	`undefined`
`headers`	`Object`	Page header configuration	`undefined`
`footers`	`Object`	Page footer configuration	`undefined`

Page Size Configuration

The pageSize object allows you to customize the dimensions of your exported DOCX document:

Property	Type	Description	Default
`width`	`string`	The width of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px).	`"21.0cm"`
`height`	`string`	The height of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px).	`"29.7cm"`

Example cURL with custom page size:

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","content":[{"type":"text","text":"Document with custom page size"}]}]}' \
    -F 'exportType=blob' \
    -F 'pageSize={"width":"21.0cm","height":"29.7cm"}'

Page Margins Configuration

The pageMargins object allows you to customize the margins of your exported DOCX document:

Property	Type	Description	Default
`top`	`string`	The top margin of the page. Can be negative. Must be a number followed by a valid unit (cm, in, pt, pc, mm, px).	`"1.0cm"`
`bottom`	`string`	The bottom margin of the page. Can be negative. Must be a number followed by a valid unit (cm, in, pt, pc, mm, px).	`"1.0cm"`
`left`	`string`	The left margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px).	`"1.0cm"`
`right`	`string`	The right margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px).	`"1.0cm"`

Example cURL with custom page margins:

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","content":[{"type":"text","text":"Document with custom margins"}]}]}' \
    -F 'exportType=blob' \
    -F 'pageMargins={"top":"2.0cm","bottom":"2.0cm","left":"1.5cm","right":"1.5cm"}'

Headers and footers

The headers and footers objects allows you to configure a set of headers and footers options for your exported DOCX.

Team License Requirement

In order to be able to use the headers and footers within the REST API you must have a Team license.

Headers Configuration

The headers object allows you to customize the headers of your exported DOCX document:

Property	Type	Description
`evenAndOddHeaders`	`boolean`	Whether to use different headers for odd and even pages
`default`	`string`	The standard default header on every page, or header on odd pages when the `evenAndOddHeaders` option is activated.
`first`	`string`	The header on the first page when the 'Different First Page' option is activated.
`even`	`string`	The header on even pages when the `evenAndOddHeaders` option is activated.

Limitations

Since API calls cannot properly serialize very complex objects or functions, the headers configuration is limited to plain strings that we then will convert for you, without any styling, to a standard DOCX heading.

Example cURL with custom headers:

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","content":[{"type":"text","text":"Document with custom headers"}]}]}' \
    -F 'exportType=blob' \
    -F 'headers={"evenAndOddHeaders":true,"default":"Default Header","first":"First Page Header","even":"Even Page Header"}'

Footers Configuration

The footers object allows you to customize the footers of your exported DOCX document:

Property	Type	Description
`evenAndOddFooters`	`boolean`	Whether to use different footers for odd and even pages
`default`	`string`	The standard default footer on every page, or footer on odd pages when the `evenAndOddFooters` option is activated.
`first`	`string`	The footer on the first page when the 'Different First Page' option is activated.
`even`	`string`	The footer on even pages when the `evenAndOddFooters` option is activated.

Limitations

Since API calls cannot properly serialize very complex objects or functions, the footers configuration is limited to plain strings that we then will convert for you, without any styling, to a standard DOCX footer.

Example cURL with custom footers:

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","content":[{"type":"text","text":"Document with custom footers"}]}]}' \
    -F 'exportType=blob' \
    -F 'footers={"evenAndOddFooters":true,"default":"Default Footer","first":"First Page Footer","even":"Even Page Footer"}'